| Name | pycityproto JSON |
| Version |
2.1.0
JSON |
| download |
| home_page | None |
| Summary | City Proto Generated Python SDK |
| upload_time | 2024-12-06 07:40:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 FIBLAB 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. |
| keywords |
city
proto
protobuf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Protos
proto 文件仓库。
## 内容
- `city.person`: 智能体
- `city.comm`: 通信
- `city.config`: 配置文件基本组件
- `city.elec`: 电网
- `city.event`: 城市事件
- `city.geo`: 坐标体系
- `city.map`: 地图
- `city.routing`: 路径规划
- `city.social`: 社交
- `city.streetview`: 街景
- `city.sync`: 全局同步器
- `city.traffic`: 交通
- `city.traffic_light`: 信控
- `city.trip`: 出行与日程
- `city.water`: 水网
## STYLE
以[buf](https://github.com/bufbuild/buf)作为 linter，按 buf 的要求作为标准。
另外，为避免二义性，所有不在完全相同命名空间下的跨文件引用均需要写出完成包名。
在相同命名空间下的，不要引入包名（主要是针对`xxx.proto`与`xxx_service.proto`）。
参考：
1. <https://developers.google.com/protocol-buffers/docs/style>
2. <https://github.com/uber/prototool/blob/dev/style/README.md>
关于 enum: prefer uber 的 style
1. 独立定义 enum，不嵌入 message
2. enum 的 item 名称加 enum name 作为前缀
## 约定
- 所有浮点数采用 double 精度。
- .proto 中不包含任何`option`，需要指定`option`的目标语言采用[buf managed mode](https://docs.buf.build/tour/use-managed-mode)进行管理。
- 采用聚合性质的 message 作为 mongodb collection 的语义表示，并便于开发 Golang 的数据读取代理。
## BSON兼容性
完全支持通过 Golang struct tag 机制实现 `bson` 到 `pb` 的快速转换，并删去不能在 `bson` 中体现的语义：
- 所有的 `oneof` 由 optional 替代，`oneof` 的功能依靠约定实现。
- 原因：struct tag 无法正确处理`oneof`，`bson`无法体现`oneof`语义，`oneof`语义实际作用价值不大，目前主要体现在`map_position`与`departure`中。
- 所有的`float`替换为`double`。
- 原因：`bson`中没有`float32`，`python`没有`float32`，`C++`在 64 位 CPU 上采用`float32`与`float64`计算速度相同。
- 所有的`uint32`替换为`int32`。
- 原因：`bson`中没有`uint`，`python`没有`uint`，同时简化`C++`与`go`代码编写（统一用`int32`）。
- 枚举在`bson`中存储由字符串替换为整数。
- struct tag 无法正确处理字符串形式的枚举。
- 丰富`bson`中的 external 数据项，解决关联到原始数据的问题。
## 更新与Golang/Python库发布
完成git仓库修改后，执行以下命令：
```bash
git tag v${major}.${minor}.${patch} # 例如 v0.1.0，设置版本号
git push --tags # 推送版本号
```
## Golang库使用
```bash
go get -u git.fiblab.net/sim/protos@v${major}.${minor}.${patch}
```
## Python库使用
```shell
pip install pycityproto
```
安装 grpcio 的过程中，如果出现
```
pip install fails with "No such file or directory: 'c++': 'c++'"
```
代表缺少 C++相关依赖。在 Debian 镜像上，执行：
```shell
sudo apt install build-essential
```
在 alpine 镜像上，执行：
```shell
apk add g++
```
### JS/TS
#### NPM
使用`npm install`命令安装SDK：
```bash
npm install @fiblab/cityproto
```
#### Yarn
使用`yarn add`命令安装SDK：
```bash
yarn add @fiblab/cityproto
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pycityproto",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "city, proto, protobuf",
"author": null,
"author_email": "Jun Zhang <zhangjun990222@gmail.com>, Junbo Yan <yanjb20thu@gmali.com>",
"download_url": "https://files.pythonhosted.org/packages/86/92/38dfc8db8a1b2c1360f7173eceb823f473ddf3023131bd0688b4417bddcb/pycityproto-2.1.0.tar.gz",
"platform": null,
"description": "# Protos\n\nproto \u6587\u4ef6\u4ed3\u5e93\u3002\n\n## \u5185\u5bb9\n\n- `city.person`: \u667a\u80fd\u4f53\n- `city.comm`: \u901a\u4fe1\n- `city.config`: \u914d\u7f6e\u6587\u4ef6\u57fa\u672c\u7ec4\u4ef6\n- `city.elec`: \u7535\u7f51\n- `city.event`: \u57ce\u5e02\u4e8b\u4ef6\n- `city.geo`: \u5750\u6807\u4f53\u7cfb\n- `city.map`: \u5730\u56fe\n- `city.routing`: \u8def\u5f84\u89c4\u5212\n- `city.social`: \u793e\u4ea4\n- `city.streetview`: \u8857\u666f\n- `city.sync`: \u5168\u5c40\u540c\u6b65\u5668\n- `city.traffic`: \u4ea4\u901a\n- `city.traffic_light`: \u4fe1\u63a7\n- `city.trip`: \u51fa\u884c\u4e0e\u65e5\u7a0b\n- `city.water`: \u6c34\u7f51\n\n## STYLE\n\n\u4ee5[buf](https://github.com/bufbuild/buf)\u4f5c\u4e3a linter\uff0c\u6309 buf \u7684\u8981\u6c42\u4f5c\u4e3a\u6807\u51c6\u3002\n\n\u53e6\u5916\uff0c\u4e3a\u907f\u514d\u4e8c\u4e49\u6027\uff0c\u6240\u6709\u4e0d\u5728\u5b8c\u5168\u76f8\u540c\u547d\u540d\u7a7a\u95f4\u4e0b\u7684\u8de8\u6587\u4ef6\u5f15\u7528\u5747\u9700\u8981\u5199\u51fa\u5b8c\u6210\u5305\u540d\u3002\n\n\u5728\u76f8\u540c\u547d\u540d\u7a7a\u95f4\u4e0b\u7684\uff0c\u4e0d\u8981\u5f15\u5165\u5305\u540d\uff08\u4e3b\u8981\u662f\u9488\u5bf9`xxx.proto`\u4e0e`xxx_service.proto`\uff09\u3002\n\n\u53c2\u8003\uff1a\n\n1. <https://developers.google.com/protocol-buffers/docs/style>\n2. <https://github.com/uber/prototool/blob/dev/style/README.md>\n\n\u5173\u4e8e enum: prefer uber \u7684 style\n\n1. \u72ec\u7acb\u5b9a\u4e49 enum\uff0c\u4e0d\u5d4c\u5165 message\n2. enum \u7684 item \u540d\u79f0\u52a0 enum name \u4f5c\u4e3a\u524d\u7f00\n\n## \u7ea6\u5b9a\n\n- \u6240\u6709\u6d6e\u70b9\u6570\u91c7\u7528 double \u7cbe\u5ea6\u3002\n- .proto \u4e2d\u4e0d\u5305\u542b\u4efb\u4f55`option`\uff0c\u9700\u8981\u6307\u5b9a`option`\u7684\u76ee\u6807\u8bed\u8a00\u91c7\u7528[buf managed mode](https://docs.buf.build/tour/use-managed-mode)\u8fdb\u884c\u7ba1\u7406\u3002\n- \u91c7\u7528\u805a\u5408\u6027\u8d28\u7684 message \u4f5c\u4e3a mongodb collection \u7684\u8bed\u4e49\u8868\u793a\uff0c\u5e76\u4fbf\u4e8e\u5f00\u53d1 Golang \u7684\u6570\u636e\u8bfb\u53d6\u4ee3\u7406\u3002\n\n## BSON\u517c\u5bb9\u6027\n\n\u5b8c\u5168\u652f\u6301\u901a\u8fc7 Golang struct tag \u673a\u5236\u5b9e\u73b0 `bson` \u5230 `pb` \u7684\u5feb\u901f\u8f6c\u6362\uff0c\u5e76\u5220\u53bb\u4e0d\u80fd\u5728 `bson` \u4e2d\u4f53\u73b0\u7684\u8bed\u4e49\uff1a\n\n- \u6240\u6709\u7684 `oneof` \u7531 optional \u66ff\u4ee3\uff0c`oneof` \u7684\u529f\u80fd\u4f9d\u9760\u7ea6\u5b9a\u5b9e\u73b0\u3002\n - \u539f\u56e0\uff1astruct tag \u65e0\u6cd5\u6b63\u786e\u5904\u7406`oneof`\uff0c`bson`\u65e0\u6cd5\u4f53\u73b0`oneof`\u8bed\u4e49\uff0c`oneof`\u8bed\u4e49\u5b9e\u9645\u4f5c\u7528\u4ef7\u503c\u4e0d\u5927\uff0c\u76ee\u524d\u4e3b\u8981\u4f53\u73b0\u5728`map_position`\u4e0e`departure`\u4e2d\u3002\n- \u6240\u6709\u7684`float`\u66ff\u6362\u4e3a`double`\u3002\n - \u539f\u56e0\uff1a`bson`\u4e2d\u6ca1\u6709`float32`\uff0c`python`\u6ca1\u6709`float32`\uff0c`C++`\u5728 64 \u4f4d CPU \u4e0a\u91c7\u7528`float32`\u4e0e`float64`\u8ba1\u7b97\u901f\u5ea6\u76f8\u540c\u3002\n- \u6240\u6709\u7684`uint32`\u66ff\u6362\u4e3a`int32`\u3002\n - \u539f\u56e0\uff1a`bson`\u4e2d\u6ca1\u6709`uint`\uff0c`python`\u6ca1\u6709`uint`\uff0c\u540c\u65f6\u7b80\u5316`C++`\u4e0e`go`\u4ee3\u7801\u7f16\u5199\uff08\u7edf\u4e00\u7528`int32`\uff09\u3002\n- \u679a\u4e3e\u5728`bson`\u4e2d\u5b58\u50a8\u7531\u5b57\u7b26\u4e32\u66ff\u6362\u4e3a\u6574\u6570\u3002\n - struct tag \u65e0\u6cd5\u6b63\u786e\u5904\u7406\u5b57\u7b26\u4e32\u5f62\u5f0f\u7684\u679a\u4e3e\u3002\n- \u4e30\u5bcc`bson`\u4e2d\u7684 external \u6570\u636e\u9879\uff0c\u89e3\u51b3\u5173\u8054\u5230\u539f\u59cb\u6570\u636e\u7684\u95ee\u9898\u3002\n\n## \u66f4\u65b0\u4e0eGolang/Python\u5e93\u53d1\u5e03\n\n\u5b8c\u6210git\u4ed3\u5e93\u4fee\u6539\u540e\uff0c\u6267\u884c\u4ee5\u4e0b\u547d\u4ee4\uff1a\n```bash\ngit tag v${major}.${minor}.${patch} # \u4f8b\u5982 v0.1.0\uff0c\u8bbe\u7f6e\u7248\u672c\u53f7\ngit push --tags # \u63a8\u9001\u7248\u672c\u53f7\n```\n\n## Golang\u5e93\u4f7f\u7528\n\n```bash\ngo get -u git.fiblab.net/sim/protos@v${major}.${minor}.${patch}\n```\n\n## Python\u5e93\u4f7f\u7528\n\n```shell\npip install pycityproto\n```\n\n\u5b89\u88c5 grpcio \u7684\u8fc7\u7a0b\u4e2d\uff0c\u5982\u679c\u51fa\u73b0\n\n```\npip install fails with \"No such file or directory: 'c++': 'c++'\"\n```\n\n\u4ee3\u8868\u7f3a\u5c11 C++\u76f8\u5173\u4f9d\u8d56\u3002\u5728 Debian \u955c\u50cf\u4e0a\uff0c\u6267\u884c\uff1a\n\n```shell\nsudo apt install build-essential\n```\n\n\u5728 alpine \u955c\u50cf\u4e0a\uff0c\u6267\u884c\uff1a\n\n```shell\napk add g++\n```\n\n### JS/TS\n\n#### NPM\n\n\u4f7f\u7528`npm install`\u547d\u4ee4\u5b89\u88c5SDK\uff1a\n```bash\nnpm install @fiblab/cityproto\n```\n\n#### Yarn\n\n\u4f7f\u7528`yarn add`\u547d\u4ee4\u5b89\u88c5SDK\uff1a\n```bash\nyarn add @fiblab/cityproto\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 FIBLAB 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. ",
"summary": "City Proto Generated Python SDK",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://cityproto.sim.fiblab.net/",
"Homepage": "https://github.com/tsinghua-fib-lab/cityproto",
"Issues": "https://github.com/tsinghua-fib-lab/cityproto/issues",
"Repository": "https://github.com/tsinghua-fib-lab/cityproto.git"
},
"split_keywords": [
"city",
" proto",
" protobuf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "861fd7cfb321bc70c8cec5ef3b8556f5b189dc697e1ccbd8cdf369ded6dcc71a",
"md5": "56e05e9a1a18cceae1a2a49105ba5d0f",
"sha256": "880adbca5eb03b1e99e763afc057b1e46b32b362d671d801ce63d7c137d0ac6e"
},
"downloads": -1,
"filename": "pycityproto-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56e05e9a1a18cceae1a2a49105ba5d0f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 198073,
"upload_time": "2024-12-06T07:40:07",
"upload_time_iso_8601": "2024-12-06T07:40:07.770196Z",
"url": "https://files.pythonhosted.org/packages/86/1f/d7cfb321bc70c8cec5ef3b8556f5b189dc697e1ccbd8cdf369ded6dcc71a/pycityproto-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "869238dfc8db8a1b2c1360f7173eceb823f473ddf3023131bd0688b4417bddcb",
"md5": "1dbe4755c0a243ca32ec754a05c6aa39",
"sha256": "21b9ec9393f51d0c5f8164798aeef730008d2a44711ff74adfabe4964edf060e"
},
"downloads": -1,
"filename": "pycityproto-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1dbe4755c0a243ca32ec754a05c6aa39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 103559,
"upload_time": "2024-12-06T07:40:08",
"upload_time_iso_8601": "2024-12-06T07:40:08.886879Z",
"url": "https://files.pythonhosted.org/packages/86/92/38dfc8db8a1b2c1360f7173eceb823f473ddf3023131bd0688b4417bddcb/pycityproto-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 07:40:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsinghua-fib-lab",
"github_project": "cityproto",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycityproto"
}
