# deproto
<div align="center">
<img src="https://raw.githubusercontent.com/MrDebugger/deproto/main/assets/icons/DEPROTO.gif" alt="deproto logo" width="200"/>
</div>
<h4 align="center">A Python package for Google Maps protobuf format</h4>
<p align="center">
<a href="https://pypi.org/project/deproto/">
<img src="https://img.shields.io/pypi/v/deproto.svg" alt="PyPI version"/>
</a>
<a href="https://pypi.org/project/deproto/">
<img src="https://img.shields.io/pypi/pyversions/deproto.svg" alt="Python versions"/>
</a>
<a href="LICENSE">
<img src="https://img.shields.io/github/license/MrDebugger/deproto.svg" alt="License"/>
</a>
<a href="https://github.com/MrDebugger/deproto/stargazers">
<img src="https://img.shields.io/github/stars/MrDebugger/deproto.svg" alt="GitHub stars"/>
</a>
<a href="https://github.com/MrDebugger/deproto/network">
<img src="https://img.shields.io/github/forks/MrDebugger/deproto.svg" alt="GitHub forks"/>
</a>
<a href="https://github.com/MrDebugger/deproto/issues">
<img src="https://img.shields.io/github/issues/MrDebugger/deproto.svg" alt="GitHub issues"/>
</a>
<a href="https://pepy.tech/project/deproto">
<img src="https://pepy.tech/badge/deproto" alt="Downloads"/>
</a>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#installation">Installation</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#building-protobuf-structures">Documentation</a> •
<a href="#advanced-usage">Advanced</a> •
<a href="#testing">Testing</a>
</p>
A Python package for decoding, manipulating, and encoding Google Maps protobuf format strings. This library provides an intuitive way to work with protobuf structures commonly found in Google Maps URLs and data.
## Features
- Decode Google Maps protobuf strings into a tree structure
- Create and modify protobuf structures using multiple approaches
- Automatic type detection and handling
- Parent-child relationship tracking
- Automatic total count management in clusters
- Tree visualization for debugging
- Support for various data types
## Installation
Install using pip:
```bash
pip install -U deproto
```
## Quick Start
```python
from deproto import Protobuf
# Example protobuf string from Google Maps
pb_string = "!1m3!1s2024!2i42!3stest"
# Create decoder instance
decoder = Protobuf(pb_string)
# Decode the string into a tree structure
cluster = decoder.decode()
# Print the tree structure
decoder.print_tree()
# Make changes to values
cluster[0][0].change("2025")
# Encode back to protobuf format
encoded = decoder.encode()
```
## Building Protobuf Structures
There are multiple ways to build protobuf structures:
### 1. Direct Construction
```python
from deproto.cluster import Cluster
from deproto.node import Node
from deproto.types import StringType, IntType
# Create a structure directly
root = Cluster(1, [
Node(1, "hello", StringType()),
Cluster(2, [
Node(1, 42, IntType())
])
])
```
### 2. Using add() with Tuples
```python
root = Cluster(1)
root.add(1, [(1, "hello"), (2, 42)]) # Types auto-detected
```
### 3. Using add() with Nodes
```python
root = Cluster(1)
root.add(1, [
Node(1, "hello", StringType()),
Node(2, 42, IntType())
])
```
### 4. Mixed Approach
```python
root = Cluster(1)
root.add(1, Node(1, "hello", StringType()))
root.add(2, [(1, 42)]) # Type auto-detected
```
## Complex Structures
You can build complex nested structures:
```python
root = Cluster(1, [
Node(1, "metadata", StringType()),
Cluster(2, [
Node(1, 42, IntType()),
Node(2, True, BoolType()),
Cluster(3, [
Node(1, "nested", StringType()),
Node(2, 3.14, IntType())
])
]),
Node(3, "end", StringType())
])
```
## Tree Visualization
The `print_tree()` method provides a clear visualization of the protobuf structure:
```
1m3
├── 1s2024
├── 2i42
└── 3stest
```
## Supported Data Types
| Type | Description | Example |
|------|-------------|---------|
| `B` | Bytes | Binary data |
| `b` | Boolean | True/False |
| `d` | Double | 3.14159 |
| `e` | Enum | 1, 2, 3 |
| `f` | Float | 3.14 |
| `i` | Int32/64 | 42 |
| `s` | String | "hello" |
| `x` | Fixed32 | 12345 |
| `y` | Fixed64 | 123456789 |
| `z` | Base64String | Encoded string |
## Advanced Usage
### Parent-Child Relationships
The library maintains parent-child relationships automatically:
```python
root = Cluster(1)
child = Cluster(2, [
Node(1, True, BoolType())
])
root.append(child)
assert child.parent == root
assert child[0].parent == child
```
### Automatic Total Management
Cluster totals are managed automatically when adding or removing nodes. The total includes both nodes and clusters:
```python
root = Cluster(1)
# Adding nodes in a cluster
root.add(1, [ # This creates: Cluster(1, [Node(1, "test"), Node(2, 42)])
Node(1, "test", StringType()),
Node(2, 42, IntType())
])
print(root.total) # 3 (1 for the cluster + 2 for the nodes)
# Adding a single node
root.add(2, Node(3, "direct", StringType()))
print(root.total) # 4 (previous 3 + 1 for the new node)
# Complex structure
root.add(3, [ # Creates nested clusters
Node(1, "hello", StringType()),
Cluster(2, [
Node(1, 42, IntType())
])
])
print(root.total) # 8 (previous 4 + 1 for new cluster + 1 for Node("hello")
# + 1 for inner Cluster + 1 for Node(42))
# Removing a cluster removes its total contribution
root.delete(3) # Removes the complex structure
print(root.total) # 4 (back to previous state)
```
Note: When using `add()` with a list, it creates a new cluster containing those items, which adds to the total count.
### Special Character Handling
String values with special characters are handled automatically:
```python
node = Node(1, "test!*", StringType())
print(node.value_raw) # "test*21*2A"
print(node.value) # "test!*"
```
## Testing
Run the test suite:
```bash
# Using pytest
pytest tests/
# With coverage
coverage run -m pytest tests/
coverage report
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
Ijaz Ur Rahim ([ijazurrahim.com](https://ijazurrahim.com) | [@MrDebugger](https://github.com/MrDebugger))
## Current Version
**0.2.1** - See [CHANGELOG.md](CHANGELOG.md) for version history and details.
Raw data
{
"_id": null,
"home_page": "https://github.com/MrDebugger/deproto",
"name": "deproto",
"maintainer": "Ijaz Ur Rahim",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "ijazkhan095@gmail.com",
"keywords": null,
"author": "Ijaz Ur Rahim",
"author_email": "ijazkhan095@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5f/47/55e00eb6c66675935a4f85e4271b878aecae75000696c511156ec5e82032/deproto-0.2.1.tar.gz",
"platform": null,
"description": "# deproto\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/MrDebugger/deproto/main/assets/icons/DEPROTO.gif\" alt=\"deproto logo\" width=\"200\"/>\n</div>\n\n<h4 align=\"center\">A Python package for Google Maps protobuf format</h4>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/deproto/\">\n <img src=\"https://img.shields.io/pypi/v/deproto.svg\" alt=\"PyPI version\"/>\n </a>\n <a href=\"https://pypi.org/project/deproto/\">\n <img src=\"https://img.shields.io/pypi/pyversions/deproto.svg\" alt=\"Python versions\"/>\n </a>\n <a href=\"LICENSE\">\n <img src=\"https://img.shields.io/github/license/MrDebugger/deproto.svg\" alt=\"License\"/>\n </a>\n <a href=\"https://github.com/MrDebugger/deproto/stargazers\">\n <img src=\"https://img.shields.io/github/stars/MrDebugger/deproto.svg\" alt=\"GitHub stars\"/>\n </a>\n <a href=\"https://github.com/MrDebugger/deproto/network\">\n <img src=\"https://img.shields.io/github/forks/MrDebugger/deproto.svg\" alt=\"GitHub forks\"/>\n </a>\n <a href=\"https://github.com/MrDebugger/deproto/issues\">\n <img src=\"https://img.shields.io/github/issues/MrDebugger/deproto.svg\" alt=\"GitHub issues\"/>\n </a>\n <a href=\"https://pepy.tech/project/deproto\">\n <img src=\"https://pepy.tech/badge/deproto\" alt=\"Downloads\"/>\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#features\">Features</a> \u2022\n <a href=\"#installation\">Installation</a> \u2022\n <a href=\"#quick-start\">Quick Start</a> \u2022\n <a href=\"#building-protobuf-structures\">Documentation</a> \u2022\n <a href=\"#advanced-usage\">Advanced</a> \u2022\n <a href=\"#testing\">Testing</a>\n</p>\n\nA Python package for decoding, manipulating, and encoding Google Maps protobuf format strings. This library provides an intuitive way to work with protobuf structures commonly found in Google Maps URLs and data.\n\n## Features\n\n- Decode Google Maps protobuf strings into a tree structure\n- Create and modify protobuf structures using multiple approaches\n- Automatic type detection and handling\n- Parent-child relationship tracking\n- Automatic total count management in clusters\n- Tree visualization for debugging\n- Support for various data types\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install -U deproto\n```\n\n## Quick Start\n\n```python\nfrom deproto import Protobuf\n\n# Example protobuf string from Google Maps\npb_string = \"!1m3!1s2024!2i42!3stest\"\n\n# Create decoder instance\ndecoder = Protobuf(pb_string)\n\n# Decode the string into a tree structure\ncluster = decoder.decode()\n\n# Print the tree structure\ndecoder.print_tree()\n\n# Make changes to values\ncluster[0][0].change(\"2025\")\n\n# Encode back to protobuf format\nencoded = decoder.encode()\n```\n\n## Building Protobuf Structures\n\nThere are multiple ways to build protobuf structures:\n\n### 1. Direct Construction\n\n```python\nfrom deproto.cluster import Cluster\nfrom deproto.node import Node\nfrom deproto.types import StringType, IntType\n\n# Create a structure directly\nroot = Cluster(1, [\n Node(1, \"hello\", StringType()),\n Cluster(2, [\n Node(1, 42, IntType())\n ])\n])\n```\n\n### 2. Using add() with Tuples\n\n```python\nroot = Cluster(1)\nroot.add(1, [(1, \"hello\"), (2, 42)]) # Types auto-detected\n```\n\n### 3. Using add() with Nodes\n\n```python\nroot = Cluster(1)\nroot.add(1, [\n Node(1, \"hello\", StringType()),\n Node(2, 42, IntType())\n])\n```\n\n### 4. Mixed Approach\n\n```python\nroot = Cluster(1)\nroot.add(1, Node(1, \"hello\", StringType()))\nroot.add(2, [(1, 42)]) # Type auto-detected\n```\n\n## Complex Structures\n\nYou can build complex nested structures:\n\n```python\nroot = Cluster(1, [\n Node(1, \"metadata\", StringType()),\n Cluster(2, [\n Node(1, 42, IntType()),\n Node(2, True, BoolType()),\n Cluster(3, [\n Node(1, \"nested\", StringType()),\n Node(2, 3.14, IntType())\n ])\n ]),\n Node(3, \"end\", StringType())\n])\n```\n\n## Tree Visualization\n\nThe `print_tree()` method provides a clear visualization of the protobuf structure:\n\n```\n1m3\n\u251c\u2500\u2500 1s2024\n\u251c\u2500\u2500 2i42\n\u2514\u2500\u2500 3stest\n```\n\n## Supported Data Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `B` | Bytes | Binary data |\n| `b` | Boolean | True/False |\n| `d` | Double | 3.14159 |\n| `e` | Enum | 1, 2, 3 |\n| `f` | Float | 3.14 |\n| `i` | Int32/64 | 42 |\n| `s` | String | \"hello\" |\n| `x` | Fixed32 | 12345 |\n| `y` | Fixed64 | 123456789 |\n| `z` | Base64String | Encoded string |\n\n## Advanced Usage\n\n### Parent-Child Relationships\n\nThe library maintains parent-child relationships automatically:\n\n```python\nroot = Cluster(1)\nchild = Cluster(2, [\n Node(1, True, BoolType())\n])\nroot.append(child)\n\nassert child.parent == root\nassert child[0].parent == child\n```\n\n### Automatic Total Management\n\nCluster totals are managed automatically when adding or removing nodes. The total includes both nodes and clusters:\n\n```python\nroot = Cluster(1)\n\n# Adding nodes in a cluster\nroot.add(1, [ # This creates: Cluster(1, [Node(1, \"test\"), Node(2, 42)])\n Node(1, \"test\", StringType()),\n Node(2, 42, IntType())\n])\nprint(root.total) # 3 (1 for the cluster + 2 for the nodes)\n\n# Adding a single node\nroot.add(2, Node(3, \"direct\", StringType()))\nprint(root.total) # 4 (previous 3 + 1 for the new node)\n\n# Complex structure\nroot.add(3, [ # Creates nested clusters\n Node(1, \"hello\", StringType()),\n Cluster(2, [\n Node(1, 42, IntType())\n ])\n])\nprint(root.total) # 8 (previous 4 + 1 for new cluster + 1 for Node(\"hello\") \n # + 1 for inner Cluster + 1 for Node(42))\n\n# Removing a cluster removes its total contribution\nroot.delete(3) # Removes the complex structure\nprint(root.total) # 4 (back to previous state)\n```\n\nNote: When using `add()` with a list, it creates a new cluster containing those items, which adds to the total count.\n\n### Special Character Handling\n\nString values with special characters are handled automatically:\n\n```python\nnode = Node(1, \"test!*\", StringType())\nprint(node.value_raw) # \"test*21*2A\"\nprint(node.value) # \"test!*\"\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Using pytest\npytest tests/\n\n# With coverage\ncoverage run -m pytest tests/\ncoverage report\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\nIjaz Ur Rahim ([ijazurrahim.com](https://ijazurrahim.com) | [@MrDebugger](https://github.com/MrDebugger))\n\n## Current Version\n\n**0.2.1** - See [CHANGELOG.md](CHANGELOG.md) for version history and details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A decoder for Google Maps protobuf format",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/MrDebugger/deproto",
"Source": "https://github.com/MrDebugger/deproto",
"Website": "https://ijazurrahim.com"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ecd63cf7446a9b4c845469f88958d6c3cbe76e6138ca5ce8068a71f132e59c8b",
"md5": "3792197aef4becf8a6a9c6c802179b34",
"sha256": "9770fee77a1b5dd90e67f40cfc8e2742f9fda9faaf423c87f3bcd38336ee760c"
},
"downloads": -1,
"filename": "deproto-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3792197aef4becf8a6a9c6c802179b34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9057,
"upload_time": "2024-12-22T10:43:57",
"upload_time_iso_8601": "2024-12-22T10:43:57.811054Z",
"url": "https://files.pythonhosted.org/packages/ec/d6/3cf7446a9b4c845469f88958d6c3cbe76e6138ca5ce8068a71f132e59c8b/deproto-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f4755e00eb6c66675935a4f85e4271b878aecae75000696c511156ec5e82032",
"md5": "b89ec0d07113f43f8a80d713980410d0",
"sha256": "ecabce2de1fd3543c6931a5449da7aa4352a146466b7b9e6e63cf267158875c7"
},
"downloads": -1,
"filename": "deproto-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "b89ec0d07113f43f8a80d713980410d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12327,
"upload_time": "2024-12-22T10:44:00",
"upload_time_iso_8601": "2024-12-22T10:44:00.853975Z",
"url": "https://files.pythonhosted.org/packages/5f/47/55e00eb6c66675935a4f85e4271b878aecae75000696c511156ec5e82032/deproto-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-22 10:44:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MrDebugger",
"github_project": "deproto",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "deproto"
}
JSON
