Metadata-Version: 2.1
Name: py2proto
Version: 2.3.1
Summary: An ORM-like Python library for generating and managing gRPC proto files and pb2 files
Author-email: Mahdi Ghasemi <mahdighasemiabari@gmail.com>
License: Copyright (c) 2024 The Python Packaging Authority
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/prodbygodfather/py2proto
Project-URL: Bug Tracker, https://github.com/prodbygodfather/py2proto/issues
Keywords: grpc,protobuf,code generation,protobuf ORM,auto create pb2 & proto file,py2proto
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio-tools >=1.30.0
Requires-Dist: grpcio >=1.30.0
Requires-Dist: Flask >=2.0.0
Requires-Dist: protobuf >=3.15.0
Requires-Dist: requests >=2.25.0

# py2proto

py2proto is a powerful Python library that simplifies the process of creating gRPC services and Protocol Buffer definitions. It automatically generates .proto files, gRPC code, and Swagger UI documentation from Python class definitions.

## Features

- Automatic generation of .proto files from Python classes
- Generation of gRPC Python code
- Swagger UI generation for easy API testing and documentation
- Support for complex data types (lists, dictionaries)
- Custom output directory setting
- Built-in Swagger UI server
- Creating server and client codes for Python and JavaScript programming languages.

## Installation

Install py2proto using pip:

```bash
pip install py2proto
```

## Usage

1. Import necessary modules:

```python
from py2proto import ProtoGenerator, relation
from typing import List, Dict
```
2. Define your message classes:
```python
class MessageProto(ProtoGenerator):
    class MessageRequest(ProtoGenerator):
        message: str
        number: int

    class MessageResponse(ProtoGenerator):
        message: str

    # relation(`relation Name`, `request function`, `returnes fucntion`)
    service = relation("SendMessage", "MessageRequest", "MessageResponse")
```
3. Generate files and run Swagger UI:
```python
if __name__ == "__main__":
if __name__ == "__main__":
    # Set output directory
    MessageProto.set_output_directory("outputs")
    
    # Generate proto file
    proto_file = MessageProto.generate_proto("messageservice", "message_service")
    
    # Generate pb2 files
    MessageProto.generate_pb2(proto_file)
    
    # Generate Swagger file
    swagger_file = MessageProto.generate_swagger(proto_file)
    
    # Generate gRPC server & client files for Python and JavaScript
    MessageProto.generate_grpc_files(['python', 'javascript'], proto_file, port=50051)
    
    # Run Swagger UI
    MessageProto.run_flask()

```

This script will generate a .proto file in the 'protos/' directory and pb2 files in the 'outputs/' directory.
Finally, the output of the generated proto file will be as follows:

## Detailed Function Explanations

### relation(method_name: str, request: str, response: str)
Defines a gRPC service method with its request and response types.

Example:
```python
service = relation("SendMessage", "MessageRequest", "MessageResponse")
```

### set_output_directory(directory: str)
Sets the output directory for generated files.

Example:
```python
MessageProto.set_output_directory("custom_output")
```

### generate_proto(package_name: str, file_name: str) -> str
Generates a .proto file based on the defined classes.

Example:
```python
proto_file = MessageProto.generate_proto("mypackage", "myservice")
```

### generate_pb2(proto_file: str)
Generates Python gRPC code from the .proto file.

Example:
```python
MessageProto.generate_pb2(proto_file)
```

### generate_swagger(proto_file: str) -> str
Generates a Swagger JSON file for API documentation.

Example:
```python
swagger_file = MessageProto.generate_swagger(proto_file)
```

### run_swagger()
Starts a Flask server to serve the Swagger UI.

Example:
```python
MessageProto.run_swagger()
```

### generate_grpc_files(languages: List[str], proto_file: str, port: int = 50051)
Generates gRPC code for the specified languages.

Example:
```python
MessageProto.generate_grpc_files(['python', 'javascript'], proto_file, port=50051)
```

## Advanced Usage
You can use complex data types in your message definitions:
```python
class ComplexProto(ProtoGenerator):
    class ComplexRequest(ProtoGenerator):
        list_field: List[str]
        dict_field: Dict[str, int]

    class ComplexResponse(ProtoGenerator):
        result: List[Dict[str, str]]

    service = relation("ComplexRequest", "ComplexResponse")
```

## Multiple Services
Define multiple services in a single Proto class:
```python
class MultiServiceProto(ProtoGenerator):
    class Request1(ProtoGenerator):
        field1: str

    class Response1(ProtoGenerator):
        result1: str

    class Request2(ProtoGenerator):
        field2: int

    class Response2(ProtoGenerator):
        result2: int

    service1 = relation("Request1", "Response1")
    service2 = relation("Request2", "Response2")
```

## Why Use py2proto?
1. Simplicity: Define your gRPC services using familiar Python syntax.
2. Automation: Automatically generate .proto files and gRPC code.
3. Documentation: Get Swagger UI documentation out of the box.
4. Flexibility: Support for complex data types and multiple services.
5. Time-saving: Reduce boilerplate code and manual proto file writing.

## Requirements

- Python 3.6+
- grpcio
- grpcio-tools
- Flask (for Swagger UI)


## Supported Data Types

py2proto supports the following Protocol Buffer data types:

- str `(string)`
- int `(int32)`
- float `(float)`
- bool `(bool)`
- bytes `(bytes)`
- "int64" `(int64)`
- "uint32" `(uint32)`
- "uint64" `(uint64)`
- "sint32" `(sint32)`
- "sint64" `(sint64)`
- "fixed32" `(fixed32)`
- "fixed64" `(fixed64)`
- "sfixed32" `(sfixed32)`
- "sfixed64" `(sfixed64)`
- "double" `(double)`
- List[Type] `(repeated)`
- Dict[KeyType, ValueType] `(map)`


## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
