# Blender Asset Tracer BAT🦇
Script to manage assets with Blender.
Blender Asset Tracer, a.k.a. BAT🦇, is the replacement of
[BAM](https://developer.blender.org/diffusion/BAM/) and
[blender-file](https://developer.blender.org/source/blender-file/)
Development is driven by choices explained in [T54125](https://developer.blender.org/T54125).
## Setting up development environment
```
python3.9 -m venv .venv
. ./.venv/bin/activate
pip install -U pip
pip install poetry black
poetry install
mypy --install-types
```
## Uploading to S3-compatible storage
BAT Pack supports uploading to S3-compatible storage. This requires a credentials file in
`~/.aws/credentials`. Replace the all-capital words to suit your situation.
[ENDPOINT]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET
You can then send a BAT Pack to the storage using a target `s3:/ENDPOINT/bucketname/path-in-bucket`,
for example:
bat pack my_blendfile.blend s3:/storage.service.cloud/jobs/awesome_work
This will upload the blend file and its dependencies to `awesome_work/my_blendfile.blend` in
the `jobs` bucket.
## Paths
There are two object types used to represent file paths. Those are strictly separated.
1. `bpathlib.BlendPath` represents a path as stored in a blend file. It consists of bytes, and is
blendfile-relative when it starts with `//`. It can represent any path from any OS Blender
supports, and as such should be used carefully.
2. `pathlib.Path` represents an actual path, possibly on the local filesystem of the computer
running BAT. Any filesystem operation (such as checking whether it exists) must be done using a
`pathlib.Path`.
When it is necessary to interpret a `bpathlib.BlendPath` as a real path instead of a sequence of
bytes, BAT first attempts to decode it as UTF-8. If that fails, the local filesystem encoding is
used. The latter is also no guarantee of correctness, though.
## Type checking
The code statically type-checked with [mypy](http://mypy-lang.org/).
Mypy likes to see the return type of `__init__` methods explicitly declared as `None`. Until issue
[#604](https://github.com/python/mypy/issues/604) is resolved, we just do this in our code too.
## Code Example
BAT can be used as a Python library to inspect the contents of blend files, without having to
open Blender itself. Here is an example showing how to determine the render engine used:
#!/usr/bin/env python3.7
import json
import sys
from pathlib import Path
from blender_asset_tracer import blendfile
from blender_asset_tracer.blendfile import iterators
if len(sys.argv) != 2:
print(f'Usage: {sys.argv[0]} somefile.blend', file=sys.stderr)
sys.exit(1)
bf_path = Path(sys.argv[1])
bf = blendfile.open_cached(bf_path)
# Get the first window manager (there is probably exactly one).
window_managers = bf.find_blocks_from_code(b'WM')
assert window_managers, 'The Blend file has no window manager'
window_manager = window_managers[0]
# Get the scene from the first window.
windows = window_manager.get_pointer((b'windows', b'first'))
for window in iterators.listbase(windows):
scene = window.get_pointer(b'scene')
break
# BAT can only return simple values, so it can't return the embedded
# struct 'r'. 'r.engine' is a simple string, though.
engine = scene[b'r', b'engine'].decode('utf8')
xsch = scene[b'r', b'xsch']
ysch = scene[b'r', b'ysch']
size = scene[b'r', b'size'] / 100.0
render_info = {
'engine': engine,
'frame_pixels': {
'x': int(xsch * size),
'y': int(ysch * size),
},
}
json.dump(render_info, sys.stdout, indent=4, sort_keys=True)
print()
To understand the naming of the properties, look at Blender's `DNA_xxxx.h` files with struct
definitions. It is those names that are accessed via `blender_asset_tracer.blendfile`. The
mapping to the names accessible in Blender's Python interface can be found in the `rna_yyyy.c`
files.
## Code Guidelines
This section documents some guidelines for the code in BAT.
### Avoiding Late Imports
All imports should be done at the top level of the file, and not inside
functions. The goal is to ensure that, once imported, a (sub)module of BAT can
be used without having to import more parts of BAT.
This requirement helps to keep Blender add-ons separated, as an add-on can
import the modules of BAT it needs, then remove them from `sys.modules` and
`sys.path` so that other add-ons don't see them. This should reduce problems
with various add-ons shipping different versions of BAT.
## Publishing a New Release
For uploading packages to PyPi, an API key is required; username+password will
not work.
First, generate an API token at https://pypi.org/manage/account/token/. Then,
use this token when publishing instead of your username and password.
As username, use `__token__`.
As password, use the token itself, including the `pypi-` prefix.
See https://pypi.org/help/#apitoken for help using API tokens to publish. This
is what I have in `~/.pypirc`:
```
[distutils]
index-servers =
bat
# Use `twine upload -r bat` to upload with this token.
[bat]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-abc-123-blablabla
```
```
. ./.venv/bin/activate
pip install twine
poetry build
twine check dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl
twine upload -r bat dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl
```
Raw data
{
"_id": null,
"home_page": "https://developer.blender.org/project/profile/79/",
"name": "blender-asset-tracer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Sybren A. St\u00fcvel",
"author_email": "sybren@blender.org",
"download_url": "https://files.pythonhosted.org/packages/e9/92/7e6f0a88e9dc401e174167e55a419d5bbf0a4e701af8e8fa9ee41dc8c3b3/blender_asset_tracer-1.18.tar.gz",
"platform": null,
"description": "# Blender Asset Tracer BAT\ud83e\udd87\n\nScript to manage assets with Blender.\n\nBlender Asset Tracer, a.k.a. BAT\ud83e\udd87, is the replacement of\n[BAM](https://developer.blender.org/diffusion/BAM/) and\n[blender-file](https://developer.blender.org/source/blender-file/)\n\nDevelopment is driven by choices explained in [T54125](https://developer.blender.org/T54125).\n\n## Setting up development environment\n\n```\npython3.9 -m venv .venv\n. ./.venv/bin/activate\npip install -U pip\npip install poetry black\npoetry install\nmypy --install-types\n```\n\n\n## Uploading to S3-compatible storage\n\nBAT Pack supports uploading to S3-compatible storage. This requires a credentials file in\n`~/.aws/credentials`. Replace the all-capital words to suit your situation.\n\n [ENDPOINT]\n aws_access_key_id = YOUR_ACCESS_KEY_ID\n aws_secret_access_key = YOUR_SECRET\n\nYou can then send a BAT Pack to the storage using a target `s3:/ENDPOINT/bucketname/path-in-bucket`,\nfor example:\n\n bat pack my_blendfile.blend s3:/storage.service.cloud/jobs/awesome_work\n\nThis will upload the blend file and its dependencies to `awesome_work/my_blendfile.blend` in\nthe `jobs` bucket.\n\n\n## Paths\n\nThere are two object types used to represent file paths. Those are strictly separated.\n\n1. `bpathlib.BlendPath` represents a path as stored in a blend file. It consists of bytes, and is\n blendfile-relative when it starts with `//`. It can represent any path from any OS Blender\n supports, and as such should be used carefully.\n2. `pathlib.Path` represents an actual path, possibly on the local filesystem of the computer\n running BAT. Any filesystem operation (such as checking whether it exists) must be done using a\n `pathlib.Path`.\n\nWhen it is necessary to interpret a `bpathlib.BlendPath` as a real path instead of a sequence of\nbytes, BAT first attempts to decode it as UTF-8. If that fails, the local filesystem encoding is\nused. The latter is also no guarantee of correctness, though.\n\n\n## Type checking\n\nThe code statically type-checked with [mypy](http://mypy-lang.org/).\n\nMypy likes to see the return type of `__init__` methods explicitly declared as `None`. Until issue\n[#604](https://github.com/python/mypy/issues/604) is resolved, we just do this in our code too.\n\n\n## Code Example\n\nBAT can be used as a Python library to inspect the contents of blend files, without having to\nopen Blender itself. Here is an example showing how to determine the render engine used:\n\n #!/usr/bin/env python3.7\n import json\n import sys\n from pathlib import Path\n\n from blender_asset_tracer import blendfile\n from blender_asset_tracer.blendfile import iterators\n\n if len(sys.argv) != 2:\n print(f'Usage: {sys.argv[0]} somefile.blend', file=sys.stderr)\n sys.exit(1)\n\n bf_path = Path(sys.argv[1])\n bf = blendfile.open_cached(bf_path)\n\n # Get the first window manager (there is probably exactly one).\n window_managers = bf.find_blocks_from_code(b'WM')\n assert window_managers, 'The Blend file has no window manager'\n window_manager = window_managers[0]\n\n # Get the scene from the first window.\n windows = window_manager.get_pointer((b'windows', b'first'))\n for window in iterators.listbase(windows):\n scene = window.get_pointer(b'scene')\n break\n\n # BAT can only return simple values, so it can't return the embedded\n # struct 'r'. 'r.engine' is a simple string, though.\n engine = scene[b'r', b'engine'].decode('utf8')\n xsch = scene[b'r', b'xsch']\n ysch = scene[b'r', b'ysch']\n size = scene[b'r', b'size'] / 100.0\n\n render_info = {\n 'engine': engine,\n 'frame_pixels': {\n 'x': int(xsch * size),\n 'y': int(ysch * size),\n },\n }\n\n json.dump(render_info, sys.stdout, indent=4, sort_keys=True)\n print()\n\nTo understand the naming of the properties, look at Blender's `DNA_xxxx.h` files with struct\ndefinitions. It is those names that are accessed via `blender_asset_tracer.blendfile`. The\nmapping to the names accessible in Blender's Python interface can be found in the `rna_yyyy.c`\nfiles.\n\n\n## Code Guidelines\n\nThis section documents some guidelines for the code in BAT.\n\n### Avoiding Late Imports\n\nAll imports should be done at the top level of the file, and not inside\nfunctions. The goal is to ensure that, once imported, a (sub)module of BAT can\nbe used without having to import more parts of BAT.\n\nThis requirement helps to keep Blender add-ons separated, as an add-on can\nimport the modules of BAT it needs, then remove them from `sys.modules` and\n`sys.path` so that other add-ons don't see them. This should reduce problems\nwith various add-ons shipping different versions of BAT.\n\n## Publishing a New Release\n\nFor uploading packages to PyPi, an API key is required; username+password will\nnot work.\n\nFirst, generate an API token at https://pypi.org/manage/account/token/. Then,\nuse this token when publishing instead of your username and password.\n\nAs username, use `__token__`.\nAs password, use the token itself, including the `pypi-` prefix.\n\nSee https://pypi.org/help/#apitoken for help using API tokens to publish. This\nis what I have in `~/.pypirc`:\n\n```\n[distutils]\nindex-servers =\n bat\n\n# Use `twine upload -r bat` to upload with this token.\n[bat]\n repository = https://upload.pypi.org/legacy/\n username = __token__\n password = pypi-abc-123-blablabla\n```\n\n```\n. ./.venv/bin/activate\npip install twine\n\npoetry build\ntwine check dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl\ntwine upload -r bat dist/blender_asset_tracer-1.18.tar.gz dist/blender_asset_tracer-1.18-*.whl\n```\n\n",
"bugtrack_url": null,
"license": "GPL-2.0+",
"summary": "BAT parses Blend files and produces dependency information. After installation run `bat --help`",
"version": "1.18",
"project_urls": {
"Homepage": "https://developer.blender.org/project/profile/79/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3caf9786d0454187fe47b680329d91631cfab8eca97bff10d434a1bc3889cb6",
"md5": "7b287a6db3cef6d4a7582a8f2d2b6592",
"sha256": "c629b8f8a9a02a5435820a213b9a7bb6c2c0f8ce04d42edd9171f6d81a2a3c5d"
},
"downloads": -1,
"filename": "blender_asset_tracer-1.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b287a6db3cef6d4a7582a8f2d2b6592",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 92925,
"upload_time": "2024-01-11T15:43:25",
"upload_time_iso_8601": "2024-01-11T15:43:25.998242Z",
"url": "https://files.pythonhosted.org/packages/b3/ca/f9786d0454187fe47b680329d91631cfab8eca97bff10d434a1bc3889cb6/blender_asset_tracer-1.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9927e6f0a88e9dc401e174167e55a419d5bbf0a4e701af8e8fa9ee41dc8c3b3",
"md5": "a181d125dccf596a3cfd4835a4ada756",
"sha256": "751918667675bd5e32fe36e1f893347abd60cae2492183853be2e858b17f2532"
},
"downloads": -1,
"filename": "blender_asset_tracer-1.18.tar.gz",
"has_sig": false,
"md5_digest": "a181d125dccf596a3cfd4835a4ada756",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 63636,
"upload_time": "2024-01-11T15:43:27",
"upload_time_iso_8601": "2024-01-11T15:43:27.495324Z",
"url": "https://files.pythonhosted.org/packages/e9/92/7e6f0a88e9dc401e174167e55a419d5bbf0a4e701af8e8fa9ee41dc8c3b3/blender_asset_tracer-1.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-11 15:43:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "blender-asset-tracer"
}
JSON