Merge pull request #19 from zerlok/feature/descriptors

feature/descriptors

README.md

@@ -1,14 +1,15 @@
 # pyprotostuben
 
-[![Python Supported versions](https://img.shields.io/pypi/pyversions/pyprotostuben.svg)](https://pypi.python.org/pypi/pyprotostuben)
+[![Latest Version](https://img.shields.io/pypi/v/pyprotostuben.svg)](https://pypi.python.org/pypi/pyprotostuben)
+[![Python Supported Versions](https://img.shields.io/pypi/pyversions/pyprotostuben.svg)](https://pypi.python.org/pypi/pyprotostuben)
 [![MyPy Strict](https://img.shields.io/badge/mypy-strict-blue)](https://mypy.readthedocs.io/en/stable/getting_started.html#strict-mode-and-configuration)
 [![Test Coverage](https://codecov.io/gh/zerlok/pyprotostuben/branch/main/graph/badge.svg)](https://codecov.io/gh/zerlok/pyprotostuben)
 [![Downloads](https://img.shields.io/pypi/dm/pyprotostuben.svg)](https://pypistats.org/packages/pyprotostuben)
 [![GitHub stars](https://img.shields.io/github/stars/zerlok/pyprotostuben)](https://github.com/zerlok/pyprotostuben/stargazers)
 
 Generate Python modules from protobuf files.
 
-## usage
+## installation
 
 [pypi package](https://pypi.python.org/pypi/pyprotostuben)
 
@@ -18,24 +19,48 @@ install with your favorite python package manager
 pip install pyprotostuben
 ```
 
+## protoc plugins
+
 ### protoc-gen-mypy-stub
 
-a protoc plugin that generates MyPy stubs
+Generates python stubs (`*_pb2.pyi` & `*_pb2_grpc.pyi` files which then used by MyPy type checker / IDE syntax highlits 
+& suggestions).
 
-#### features
+**features:**
 
 * choose message structure immutability / mutability
 * choose async / sync grpc module stubs
 * grpc servicer abstract methods have full signature (with appropriate type args in generics), thus it is easier to
   implement methods in IDE
 
-#### flags
+**plugin options:**
 
 * `message-mutable` -- add setters for fields, use mutable containers
 * `message-all-init-args-optional` -- each field is optional in message constructor (event if required)
 * `grpc-sync` -- use sync grpc stubs instead of grpc.aio module and async defs
 * `grpc-skip-servicer` -- don't generate code for servicers
 * `grpc-skip-stub` -- don't generate code for stubs
+* `no-parallel` -- disable multiprocessing
+* `debug` -- turn on plugin debugging
+
+### protoc-gen-brokrpc
+
+Generates `*_brokrpc.py` modules for [BrokRPC](https://github.com/zerlok/BrokRPC) framework. This is similar to gRPC 
+codegen (`*_pb2_grpc.py` modules).
+
+**plugin options:**
+
+* `no-parallel` -- disable multiprocessing
+* `debug` -- turn on plugin debugging
+
+### protoc-gen-echo
+
+Saves protoc plugin input to a file. Helps develop protoc plugins.
+
+**plugin options:**
+
+* `format={binary|json}` (default = `json`) -- specify output format
+* `dest={path}` (default = `request.json`) -- specify file destination
 
 ## examples
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pyprotostuben"
-version = "0.3.0"
+version = "0.3.1"
 description = "Generate Python MyPy stub modules from protobuf files."
 authors = ["zerlok <[email protected]>"]
 readme = "README.md"
@@ -19,6 +19,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 
+[tool.poetry.urls]
+Homepage = "https://github.com/zerlok/pyprotostuben"
+Issues = "https://github.com/zerlok/pyprotostuben/issues"
+
 [tool.poetry.scripts]
 protoc-gen-mypy-stub = "pyprotostuben.protoc:gen_mypy_stub"
 protoc-gen-brokrpc = "pyprotostuben.protoc:gen_brokrpc"
@@ -36,7 +40,7 @@ pytest-cov = "^6.0.0"
 pytest-mypy-plugins = "^3.1.2"
 ruff = "^0.7.4"
 grpc-stubs = "^1.53.0.5"
-BrokRPC = { version = "^0.1.0", python = ">=3.12,<4.0" }
+BrokRPC = { version = "^0.2.0", python = ">=3.12,<4.0" }
 
 
 [build-system]

src/pyprotostuben/codegen/abc.py

@@ -3,7 +3,6 @@
 
 from google.protobuf.compiler.plugin_pb2 import CodeGeneratorRequest, CodeGeneratorResponse
 
-from pyprotostuben.codegen.model import GeneratedItem
 from pyprotostuben.protobuf.file import ProtoFile
 
 
@@ -15,5 +14,5 @@ def run(self, request: CodeGeneratorRequest) -> CodeGeneratorResponse:
 
 class ProtoFileGenerator(metaclass=abc.ABCMeta):
     @abc.abstractmethod
-    def run(self, file: ProtoFile) -> t.Sequence[GeneratedItem]:
+    def run(self, file: ProtoFile) -> t.Sequence[CodeGeneratorResponse.File]:
         raise NotImplementedError