# django-simple-grpc
**django-simple-grpc** is a developer-friendly Django package that makes using gRPC in Django **simple, fast, and automatic**.
It supports both server and client code, and includes powerful Django management commands for generating `.proto` files and gRPC services from your existing models.
---
## 🚀 Features
- ✅ Auto-generate `.proto` files from Django models
- ✅ Compile `.proto` files to Python gRPC stubs using `grpcio-tools`
- ✅ Run gRPC servers using a clean `run_grpc` command
- ✅ Build gRPC clients easily with `GRPCClient`
- ✅ Works with Django 3.2+ (up to 5.x)
- ✅ Compatible with Python 3.7–3.12
---
## 📦 Installation
```bash
pip install django-simple-grpc
```
---
## ⚙️ Setup in Django
Add to your `settings.py`:
```python
INSTALLED_APPS = [
...
"django_simple_grpc",
]
```
Then add the gRPC configuration:
```python
# gRPC settings
GRPC_SERVER_PORT = 50051
GRPC_SERVER_ADDRESS = "localhost:50051"
# Replace <your_app> and <YourServiceName> with your actual values
GRPC_SERVICE_REGISTER = "grpc_generated.<your_app>_pb2_grpc.add_<YourServiceName>Servicer_to_server"
GRPC_SERVICE_IMPL = "<your_app>.grpc_service.<YourServiceName>Servicer"
```
🔁 Example if your app is called `store` and your service is `ProductService`:
```python
GRPC_SERVICE_REGISTER = "grpc_generated.store_pb2_grpc.add_ProductServiceServicer_to_server"
GRPC_SERVICE_IMPL = "store.grpc_service.ProductServiceServicer"
```
---
## 🛠️ Basic Usage
### 1. Generate `.proto` file from your model
```bash
python manage.py grpc_auto_proto <app_name> <ServiceName>
```
Example:
```bash
python manage.py grpc_auto_proto book BookService
```
---
### 2. Compile the `.proto` into Python gRPC code
```bash
python manage.py grpc_generate
```
This creates Python files in `grpc_generated/`.
---
### 3. Implement the service logic
```python
# book/grpc_service.py
from grpc_generated import book_pb2, book_pb2_grpc
from book.models import Book
from google.protobuf import empty_pb2
class BookServiceServicer(book_pb2_grpc.BookServiceServicer):
def ListBooks(self, request, context):
books = Book.objects.all()
return book_pb2.BookList(
items=[
book_pb2.Book(id=b.id, title=b.title, author=b.author)
for b in books
]
)
```
---
### 4. Run the gRPC server
```bash
python manage.py run_grpc
```
---
## 🛰️ Client Example
Create a simple test script like `test_client.py`:
```python
import os
import sys
# Add grpc_generated/ to Python path
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "grpc_generated"))
# Setup Django settings
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "yourproject.settings")
import django
django.setup()
from grpc_generated import book_pb2, book_pb2_grpc
from google.protobuf.empty_pb2 import Empty
from django_simple_grpc.client import GRPCClient
client = GRPCClient(book_pb2_grpc.BookServiceStub)
response = client.call("ListBooks", Empty())
for book in response.items:
print(f"{book.id}: {book.title} by {book.author}")
```
---
## 🧪 Test the Full Flow
### Terminal 1 – Start the gRPC server
```bash
python manage.py run_grpc
```
---
### Terminal 2 – Run the test client
```bash
python test_client.py
```
✅ You should see a list of books from your Django database via gRPC!
---
## 📄 License
This project is open-source under the **MIT License** with an attribution clause.
You are free to use it, but **please give credit** and **do not rebrand or publish it under your own name**.
---
## 💬 Contributions
Pull requests and feedback are welcome!
Fork it, try it, and use it in your Django gRPC apps.
---
Made with ❤️ by HF
Raw data
{
"_id": null,
"home_page": "https://github.com/HosseinFattahi/django-simple-grpc",
"name": "django-simple-grpc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django grpc grpcio microservices python server client",
"author": "HF",
"author_email": "hofattahi98@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f7/a3/965341000bee424ec6ac0995ccdc2bd9e4d7a633383273aed7017c11a294/django_simple_grpc-0.1.1.tar.gz",
"platform": null,
"description": "# django-simple-grpc\n\n**django-simple-grpc** is a developer-friendly Django package that makes using gRPC in Django **simple, fast, and automatic**.\n\nIt supports both server and client code, and includes powerful Django management commands for generating `.proto` files and gRPC services from your existing models.\n\n---\n\n## \ud83d\ude80 Features\n\n- \u2705 Auto-generate `.proto` files from Django models \n- \u2705 Compile `.proto` files to Python gRPC stubs using `grpcio-tools` \n- \u2705 Run gRPC servers using a clean `run_grpc` command \n- \u2705 Build gRPC clients easily with `GRPCClient` \n- \u2705 Works with Django 3.2+ (up to 5.x) \n- \u2705 Compatible with Python 3.7\u20133.12 \n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install django-simple-grpc\n```\n\n---\n\n## \u2699\ufe0f Setup in Django\n\nAdd to your `settings.py`:\n\n```python\nINSTALLED_APPS = [\n ...\n \"django_simple_grpc\",\n]\n```\n\nThen add the gRPC configuration:\n\n```python\n# gRPC settings\nGRPC_SERVER_PORT = 50051\nGRPC_SERVER_ADDRESS = \"localhost:50051\"\n\n# Replace <your_app> and <YourServiceName> with your actual values\nGRPC_SERVICE_REGISTER = \"grpc_generated.<your_app>_pb2_grpc.add_<YourServiceName>Servicer_to_server\"\nGRPC_SERVICE_IMPL = \"<your_app>.grpc_service.<YourServiceName>Servicer\"\n```\n\n\ud83d\udd01 Example if your app is called `store` and your service is `ProductService`:\n\n```python\nGRPC_SERVICE_REGISTER = \"grpc_generated.store_pb2_grpc.add_ProductServiceServicer_to_server\"\nGRPC_SERVICE_IMPL = \"store.grpc_service.ProductServiceServicer\"\n```\n\n---\n\n## \ud83d\udee0\ufe0f Basic Usage\n\n### 1. Generate `.proto` file from your model\n\n```bash\npython manage.py grpc_auto_proto <app_name> <ServiceName>\n```\n\nExample:\n\n```bash\npython manage.py grpc_auto_proto book BookService\n```\n\n---\n\n### 2. Compile the `.proto` into Python gRPC code\n\n```bash\npython manage.py grpc_generate\n```\n\nThis creates Python files in `grpc_generated/`.\n\n---\n\n### 3. Implement the service logic\n\n```python\n# book/grpc_service.py\n\nfrom grpc_generated import book_pb2, book_pb2_grpc\nfrom book.models import Book\nfrom google.protobuf import empty_pb2\n\nclass BookServiceServicer(book_pb2_grpc.BookServiceServicer):\n def ListBooks(self, request, context):\n books = Book.objects.all()\n return book_pb2.BookList(\n items=[\n book_pb2.Book(id=b.id, title=b.title, author=b.author)\n for b in books\n ]\n )\n```\n\n---\n\n### 4. Run the gRPC server\n\n```bash\npython manage.py run_grpc\n```\n\n---\n\n## \ud83d\udef0\ufe0f Client Example\n\nCreate a simple test script like `test_client.py`:\n\n```python\nimport os\nimport sys\n\n# Add grpc_generated/ to Python path\nsys.path.insert(0, os.path.join(os.path.dirname(__file__), \"grpc_generated\"))\n\n# Setup Django settings\nos.environ.setdefault(\"DJANGO_SETTINGS_MODULE\", \"yourproject.settings\")\nimport django\ndjango.setup()\n\nfrom grpc_generated import book_pb2, book_pb2_grpc\nfrom google.protobuf.empty_pb2 import Empty\nfrom django_simple_grpc.client import GRPCClient\n\nclient = GRPCClient(book_pb2_grpc.BookServiceStub)\nresponse = client.call(\"ListBooks\", Empty())\n\nfor book in response.items:\n print(f\"{book.id}: {book.title} by {book.author}\")\n```\n\n---\n\n## \ud83e\uddea Test the Full Flow\n\n### Terminal 1 \u2013 Start the gRPC server\n\n```bash\npython manage.py run_grpc\n```\n\n---\n\n### Terminal 2 \u2013 Run the test client\n\n```bash\npython test_client.py\n```\n\n\u2705 You should see a list of books from your Django database via gRPC!\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is open-source under the **MIT License** with an attribution clause. \nYou are free to use it, but **please give credit** and **do not rebrand or publish it under your own name**.\n\n---\n\n## \ud83d\udcac Contributions\n\nPull requests and feedback are welcome! \nFork it, try it, and use it in your Django gRPC apps.\n\n---\n\nMade with \u2764\ufe0f by HF\n",
"bugtrack_url": null,
"license": null,
"summary": "Simplify gRPC server and client usage in Django apps.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/HosseinFattahi/django-simple-grpc/issues",
"Homepage": "https://github.com/HosseinFattahi/django-simple-grpc",
"Source": "https://github.com/HosseinFattahi/django-simple-grpc"
},
"split_keywords": [
"django",
"grpc",
"grpcio",
"microservices",
"python",
"server",
"client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "61c269ddddd03cb67f2232a0c7ed9cfe806bc38b9c30b07d953f8d4979b05237",
"md5": "6498a1e9bb3410d2cc11aeb094be2468",
"sha256": "5ebaf3b7fb52dea2085b8188201009d01c6772b8714da5f27e0e8f793d5e4e42"
},
"downloads": -1,
"filename": "django_simple_grpc-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6498a1e9bb3410d2cc11aeb094be2468",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9419,
"upload_time": "2025-03-21T20:45:39",
"upload_time_iso_8601": "2025-03-21T20:45:39.812998Z",
"url": "https://files.pythonhosted.org/packages/61/c2/69ddddd03cb67f2232a0c7ed9cfe806bc38b9c30b07d953f8d4979b05237/django_simple_grpc-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f7a3965341000bee424ec6ac0995ccdc2bd9e4d7a633383273aed7017c11a294",
"md5": "48cf4cc7209fae917bc06d7c9f941d00",
"sha256": "f93e8679bce9927b2e1141ded2bb299f5078177a72efec47aa2c2b6cb4697606"
},
"downloads": -1,
"filename": "django_simple_grpc-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "48cf4cc7209fae917bc06d7c9f941d00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8828,
"upload_time": "2025-03-21T20:45:41",
"upload_time_iso_8601": "2025-03-21T20:45:41.319004Z",
"url": "https://files.pythonhosted.org/packages/f7/a3/965341000bee424ec6ac0995ccdc2bd9e4d7a633383273aed7017c11a294/django_simple_grpc-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-21 20:45:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HosseinFattahi",
"github_project": "django-simple-grpc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asgiref",
"specs": [
[
"==",
"3.8.1"
]
]
},
{
"name": "Django",
"specs": [
[
"==",
"5.1.7"
]
]
},
{
"name": "grpcio",
"specs": [
[
"==",
"1.71.0"
]
]
},
{
"name": "grpcio-tools",
"specs": [
[
"==",
"1.71.0"
]
]
},
{
"name": "protobuf",
"specs": [
[
"==",
"5.29.4"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"77.0.3"
]
]
},
{
"name": "sqlparse",
"specs": [
[
"==",
"0.5.3"
]
]
}
],
"lcname": "django-simple-grpc"
}
JSON
