# What is this?
A basic [Content Addressable aRchive](https://ipld.io/specs/transport/car/) (CAR) v1 reader and writer. Enough to get you reading from the [ATProto](https://atproto.com/) firehose and emitting blocks from your own PDS. [More details on ATProto's CAR usage here.](https://atproto.com/specs/repository#car-file-serialization)
## Installation
```bash
pip install carbox
```
## Basic Usage
```python
from datetime import datetime
from carbox.car import Block, read_car, write_car
from carbox.message import read_event_pair
import dag_cbor
# Where websocket_msg is a message comes from the firehose.
header, event = read_event_pair(websocket_msg)
roots, blocks = read_car(event['blocks'])
records = [dag_cbor.decode(block) for block in blocks]
record = {
'$type': 'app.bsky.feed.post',
'text': 'Hello, world!',
'createdAt': datetime.now().isoformat(),
}
block = Block(decoded=record)
car_bytes = write_car(block.cid, [block])
```
## Changelog
### 0.3 - 2024-03-16
* Relax dependencies to allow minor version upgrades.
### 0.2 - 2023-09-07
Add write support via `car.write_car`. See usage example above for details.
### 0.0.1 - 2023-05-07
Initial release.
## Release instructions
Here's how to package, test, and ship a new release.
1. Run the unit tests.
```sh
source [path_to_virtualenv]/bin/activate.csh
pytest
```
1. Bump the version number in `pyproject.toml`. `git grep` the old version number to make sure it only appears in the changelog. Change the current changelog entry in `README.md` for this new version from _unreleased_ to the current date.
1. `git commit -am 'release vX.Y'`
1. Upload to [test.pypi.org](https://test.pypi.org/) for testing.
```sh
poetry build
setenv ver X.Y
twine upload -r pypitest dist/carbox-$ver*
```
1. Install from test.pypi.org.
```sh
cd /tmp
python3 -m venv local
source local/bin/activate.csh
# make sure we force pip to use the uploaded version
pip3 uninstall carbox
pip3 install --upgrade pip
pip3 install -i https://test.pypi.org/simple --extra-index-url https://pypi.org/simple carbox==$ver
deactivate
```
1. Smoke test that the code trivially loads and runs:
```sh
from carbox.car import Block, read_car, write_car
block = Block(decoded={'foo': ['bar', 2, 3.14]})
car_bytes = write_car([block.cid], [block])
assert read_car(car_bytes) == ([block.cid], [block])
```
1. Tag the release in git. In the tag message editor, delete the generated comments at bottom, leave the first line blank (to omit the release "title" in github), put `### Notable changes` on the second line, then copy and paste this version's changelog contents below it.
```sh
git tag -a v$ver --cleanup=verbatim
git push && git push --tags
```
1. [Click here to draft a new release on GitHub.](https://github.com/snarfed/carbox/releases/new) Enter `vX.Y` in the _Tag version_ box. Leave _Release title_ empty. Copy `### Notable changes` and the changelog contents into the description text box.
1. Upload to [pypi.org](https://pypi.org/)!
```sh
twine upload dist/carbox-$ver*
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jbn/carbox",
"name": "carbox",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "generativist",
"author_email": "jbn@abreka.com",
"download_url": "https://files.pythonhosted.org/packages/be/0c/38765d95b1b96c87f566b7b157d9608d77b0190883af4cf6863bee299f27/carbox-0.3.tar.gz",
"platform": null,
"description": "\n\n![A Box](https://github.com/snarfed/carbox/raw/main/logo.png \"A helmet for the psychonaut\")\n\n# What is this?\n\nA basic [Content Addressable aRchive](https://ipld.io/specs/transport/car/) (CAR) v1 reader and writer. Enough to get you reading from the [ATProto](https://atproto.com/) firehose and emitting blocks from your own PDS. [More details on ATProto's CAR usage here.](https://atproto.com/specs/repository#car-file-serialization)\n\n## Installation\n\n```bash\npip install carbox\n```\n\n## Basic Usage\n\n```python\nfrom datetime import datetime\nfrom carbox.car import Block, read_car, write_car\nfrom carbox.message import read_event_pair\nimport dag_cbor\n\n# Where websocket_msg is a message comes from the firehose.\nheader, event = read_event_pair(websocket_msg)\nroots, blocks = read_car(event['blocks'])\nrecords = [dag_cbor.decode(block) for block in blocks]\n\nrecord = {\n '$type': 'app.bsky.feed.post',\n 'text': 'Hello, world!',\n 'createdAt': datetime.now().isoformat(),\n}\nblock = Block(decoded=record)\ncar_bytes = write_car(block.cid, [block])\n```\n\n\n## Changelog\n\n### 0.3 - 2024-03-16\n\n* Relax dependencies to allow minor version upgrades.\n\n### 0.2 - 2023-09-07\n\nAdd write support via `car.write_car`. See usage example above for details.\n\n### 0.0.1 - 2023-05-07\n\nInitial release.\n\n\n## Release instructions\n\nHere's how to package, test, and ship a new release.\n\n1. Run the unit tests.\n\n ```sh\n source [path_to_virtualenv]/bin/activate.csh\n pytest\n ```\n1. Bump the version number in `pyproject.toml`. `git grep` the old version number to make sure it only appears in the changelog. Change the current changelog entry in `README.md` for this new version from _unreleased_ to the current date.\n1. `git commit -am 'release vX.Y'`\n1. Upload to [test.pypi.org](https://test.pypi.org/) for testing.\n\n ```sh\n poetry build\n setenv ver X.Y\n twine upload -r pypitest dist/carbox-$ver*\n ```\n1. Install from test.pypi.org.\n\n ```sh\n cd /tmp\n python3 -m venv local\n source local/bin/activate.csh\n # make sure we force pip to use the uploaded version\n pip3 uninstall carbox\n pip3 install --upgrade pip\n pip3 install -i https://test.pypi.org/simple --extra-index-url https://pypi.org/simple carbox==$ver\n deactivate\n ```\n1. Smoke test that the code trivially loads and runs:\n\n ```sh\n from carbox.car import Block, read_car, write_car\n\n block = Block(decoded={'foo': ['bar', 2, 3.14]})\n car_bytes = write_car([block.cid], [block])\n assert read_car(car_bytes) == ([block.cid], [block])\n ```\n1. Tag the release in git. In the tag message editor, delete the generated comments at bottom, leave the first line blank (to omit the release \"title\" in github), put `### Notable changes` on the second line, then copy and paste this version's changelog contents below it.\n\n ```sh\n git tag -a v$ver --cleanup=verbatim\n git push && git push --tags\n ```\n1. [Click here to draft a new release on GitHub.](https://github.com/snarfed/carbox/releases/new) Enter `vX.Y` in the _Tag version_ box. Leave _Release title_ empty. Copy `### Notable changes` and the changelog contents into the description text box.\n1. Upload to [pypi.org](https://pypi.org/)!\n\n ```sh\n twine upload dist/carbox-$ver*\n ```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "",
"version": "0.3",
"project_urls": {
"Documentation": "https://github.com/jbn/carbox",
"Homepage": "https://github.com/jbn/carbox",
"Repository": "https://github.com/jbn/carbox"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd8e81fa3a426c135bfc17a972e9f8a9fd14cc5af17bef756d7b2d2e061d7001",
"md5": "5bfea7285705ef5113029e9628cd670b",
"sha256": "3ca4d2a3e50ff4c807673e354dc6704c9ec8b61929629dbfa803d4e56e87451d"
},
"downloads": -1,
"filename": "carbox-0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bfea7285705ef5113029e9628cd670b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 13540,
"upload_time": "2024-03-16T20:13:24",
"upload_time_iso_8601": "2024-03-16T20:13:24.275047Z",
"url": "https://files.pythonhosted.org/packages/dd/8e/81fa3a426c135bfc17a972e9f8a9fd14cc5af17bef756d7b2d2e061d7001/carbox-0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be0c38765d95b1b96c87f566b7b157d9608d77b0190883af4cf6863bee299f27",
"md5": "bc3046598c9bd154884434c3dd6aceca",
"sha256": "f19eb5a456a378073e6ca31c4ba0a6a30249f49c94850c60e5aecb2dcc5544ba"
},
"downloads": -1,
"filename": "carbox-0.3.tar.gz",
"has_sig": false,
"md5_digest": "bc3046598c9bd154884434c3dd6aceca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 13444,
"upload_time": "2024-03-16T20:14:19",
"upload_time_iso_8601": "2024-03-16T20:14:19.429737Z",
"url": "https://files.pythonhosted.org/packages/be/0c/38765d95b1b96c87f566b7b157d9608d77b0190883af4cf6863bee299f27/carbox-0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 20:14:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jbn",
"github_project": "carbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "carbox"
}
JSON
