diff --git a/CHANGELOG.md b/CHANGELOG.md index 08855cb87..383d3f78a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +- Versions suffixed with `b*` are in `beta` and can be installed with `pip install --pre betterproto`. + +## [2.0.0b1] - 2020-07-04 + +[Upgrade Guide](./docs/upgrading.md) + +> Several bugfixes and improvements required or will require small breaking changes, necessitating a new version. +> `2.0.0` will be released once the interface is stable. + +- Add support for gRPC and **stream-stream** [#83](https://github.com/danielgtaylor/python-betterproto/pull/83) +- Switch from to `poetry` for development [#75](https://github.com/danielgtaylor/python-betterproto/pull/75) +- Fix No arguments are generated for stub methods when using import with proto definition +- Fix two packages with the same name suffix should not cause naming conflict [#25](https://github.com/danielgtaylor/python-betterproto/issues/25) + +- Fix Import child package from root [#57](https://github.com/danielgtaylor/python-betterproto/issues/57) +- Fix Import child package from package [#58](https://github.com/danielgtaylor/python-betterproto/issues/58) +- Fix Import parent package from child package [#59](https://github.com/danielgtaylor/python-betterproto/issues/59) +- Fix Import root package from child package [#60](https://github.com/danielgtaylor/python-betterproto/issues/60) +- Fix Import root package from root [#61](https://github.com/danielgtaylor/python-betterproto/issues/61) + +- Fix ALL_CAPS message fields are parsed incorrectly. [#11](https://github.com/danielgtaylor/python-betterproto/issues/11) + ## [1.2.5] - 2020-04-27 - Add .j2 suffix to python template names to avoid confusing certain build tools [#72](https://github.com/danielgtaylor/python-betterproto/pull/72) diff --git a/README.md b/README.md index 15e85a7cf..d1facad77 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ This project exists because I am unhappy with the state of the official Google p This project is a reimplementation from the ground up focused on idiomatic modern Python to help fix some of the above. While it may not be a 1:1 drop-in replacement due to changed method names and call patterns, the wire format is identical. -## Installation & Getting Started +## Installation First, install the package. Note that the `[compiler]` feature flag tells it to install extra dependencies only needed by the `protoc` plugin: @@ -52,6 +52,12 @@ pip install "betterproto[compiler]" pip install betterproto ``` +*Betterproto* is under active development. To install the latest beta version, use `pip install --pre betterproto`. + +## Getting Started + +### Compiling proto files + Now, given you installed the compiler and have a proto file, e.g `example.proto`: ```protobuf @@ -149,7 +155,7 @@ service Echo { You can use it like so (enable async in the interactive shell first): -```py +```python >>> import echo >>> from grpclib.client import Channel @@ -174,8 +180,8 @@ Both serializing and parsing are supported to/from JSON and Python dictionaries For compatibility the default is to convert field names to `camelCase`. You can control this behavior by passing a casing value, e.g: -```py ->>> MyMessage().to_dict(casing=betterproto.Casing.SNAKE) +```python +MyMessage().to_dict(casing=betterproto.Casing.SNAKE) ``` ### Determining if a message was sent @@ -300,7 +306,22 @@ datetime.datetime(2019, 1, 1, 11, 59, 58, 800000, tzinfo=datetime.timezone.utc) Join us on [Slack](https://join.slack.com/t/betterproto/shared_invite/zt-f0n0uolx-iN8gBNrkPxtKHTLpG3o1OQ)! -First, make sure you have Python 3.6+ and `poetry` installed, along with the official [Protobuf Compiler](https://github.com/protocolbuffers/protobuf/releases) for your platform. Then: +### Requirements + +- Python (3.6 or higher) + +- [protoc](https://grpc.io/docs/protoc-installation/) (3.12 or higher) + *Needed to compile `.proto` files and run the tests* + +- [poetry](https://python-poetry.org/docs/#installation) + *Needed to install dependencies in a virtual environment* + +- make ([ubuntu](https://www.howtoinstall.me/ubuntu/18-04/make/), [windows](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows), [mac](https://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)) + + *Needed to conveniently run development tasks.* + *Alternatively, manually run the commands defined in the [Makefile](./Makefile)* + +### Setup ```sh # Get set up with the virtual env & dependencies @@ -310,7 +331,7 @@ poetry install poetry shell ``` -To benefit from the collection of standard development tasks ensure you have make installed and run `make help` to see available tasks. +Run `make help` to see all available development tasks. ### Code style diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 000000000..84534a35a --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,16 @@ +# Upgrade Guide + +## [1.2.5] to [2.0.0b1] + +### Updated package structures + +Generated code now strictly follows the *package structure* of the `.proto` files. +Consequently `.proto` files without a package will be combined in a single `__init__.py` file. +To avoid overwriting existing `__init__.py` files, its best to compile into a dedicated subdirectory. + +Upgrading: + +- Remove your previously compiled `.py` files. +- Create a new *empty* directory, e.g. `generated` or `lib/generated/proto` etcetera. +- Regenerate your python files into this directory +- Update import statements, e.g. `import ExampleMessage from generated` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index f1e966b39..2096e9fae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "betterproto" -version = "1.2.5" +version = "2.0.0b1" description = "A better Protobuf / gRPC generator & library" authors = ["Daniel G. Taylor "] readme = "README.md"