diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..19bc9cc --- /dev/null +++ b/.editorconfig @@ -0,0 +1,22 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: Apache-2.0 + +# Editor configuration, see http://editorconfig.org +root = true + +[*] +charset = utf-8 +end_of_line = lf # lf = \n, crlf = \r\n +indent_size = 4 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +# no whitespace trimming in Markdown +[*.md] +max_line_length = 0 +trim_trailing_whitespace = false + +# windows shell scripts shall get the Carriage-Return-Line-Feed (\r\n) line ending +[{*.bat,*.cmd}] +end_of_line = crlf diff --git a/.git_archival.txt b/.git_archival.txt new file mode 100644 index 0000000..1c1d2e8 --- /dev/null +++ b/.git_archival.txt @@ -0,0 +1,7 @@ +Copyright DB Netz AG and contributors +SPDX-License-Identifier: CC0-1.0 + +node: $Format:%H$ +node-date: $Format:%cI$ +describe-name: $Format:%(describe:tags=true)$ +ref-names: $Format:%D$ diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..de62da1 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,11 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +* text=auto + +*.{cmd,[cC][mM][dD]} text eol=crlf +*.{bat,[bB][aA][tT]} text eol=crlf + +*.{sh,py} text eol=lf + +.git_archival.txt export-subst diff --git a/.github/workflows/build-test-publish.yml b/.github/workflows/build-test-publish.yml new file mode 100644 index 0000000..2a76bd9 --- /dev/null +++ b/.github/workflows/build-test-publish.yml @@ -0,0 +1,78 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +name: Build + +on: + push: + branches: ["*"] + pull_request: [master] + tags: ["v*.*.*"] + +jobs: + test: + name: Test with Python ${{matrix.python_version}} on ${{matrix.os}} + runs-on: ${{matrix.os}} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + python_version: + - "3.8" + - "3.9" + - "3.10" + - "3.11" + include: + - os: windows-latest + python_version: "3.8" + steps: + - uses: actions/checkout@v2 + - name: Set up Python ${{matrix.python_version}} + uses: actions/setup-python@v2 + with: + python-version: ${{matrix.python_version}} + - uses: actions/cache@v2 + with: + path: ~/.cache/pip + key: ${{runner.os}}-pip-${{hashFiles('pyproject.toml')}} + restore-keys: | + ${{runner.os}}-pip- + ${{runner.os}}- + - name: Upgrade Pip + run: |- + python -m pip install -U pip + - name: Install test dependencies + run: |- + python -m pip install '.[test]' + - name: Run unit tests + run: |- + python -m pytest --cov-report=term --cov=raillabel_providerkit --rootdir=. + + publish: + name: Publish artifacts + runs-on: ubuntu-latest + needs: test + steps: + - uses: actions/checkout@v2 + - name: Setup Python + uses: actions/setup-python@v2 + with: + python-version: "3.8" + - name: Install dependencies + run: |- + python -m pip install -U pip + python -m pip install build twine + - name: Build packages + run: |- + python -m build + - name: Verify packages + run: |- + python -m twine check dist/* + - name: Upload artifacts + uses: actions/upload-artifact@v2 + with: + name: Artifacts + path: 'dist/*' + - name: Publish to PyPI (release only) + if: startsWith(github.ref, 'refs/tags/v') + run: python -m twine upload -u __token__ -p ${{ secrets.PYPI_TOKEN }} --non-interactive dist/* diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..0a0556e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +name: Docs + +on: + push: + branches: ["main"] + +jobs: + sphinx: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - uses: actions/setup-python@v2 + with: + python-version: "3.8" + - name: Upgrade pip + run: | + python -m pip install -U pip + - name: Install dependencies + run: | + python -m pip install '.[docs]' + - name: Auto-generate APIDOC sources + run: |- + sphinx-apidoc --output-dir docs/source/code --force . + - name: Create docs + run: | + make -C docs html + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + force_orphan: true + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build/html diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..f4439fd --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,42 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +name: Lint + +on: + push: + branches: ["*"] + +jobs: + pre-commit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: "3.8" + - name: Upgrade pip + run: |- + python -m pip install -U pip + - name: Install pre-commit + run: |- + python -m pip install pre-commit types-docutils + - name: Run Pre-Commit + run: |- + pre-commit run --all-files + pylint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: "3.8" + - name: Upgrade pip + run: |- + python -m pip install -U pip + - name: Install pylint + run: |- + python -m pip install pylint + - name: Run pylint + run: |- + pylint -dfixme raillabel_providerkit || exit $(($? & ~24)) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0598a50 --- /dev/null +++ b/.gitignore @@ -0,0 +1,169 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ +docs/source/code/ +docs/source/_build + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# VS Code +.vscode + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# Mac related +.DS_Store + +# Project related +playground/ +scripts/ +tests/__test_assets__/openlabel_v1_short.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..777347f --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,99 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +default_install_hook_types: [commit-msg, pre-commit] +default_stages: [commit, merge-commit] +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.2.0 + hooks: + - id: check-added-large-files + - id: check-ast + - id: check-builtin-literals + - id: check-case-conflict + - id: check-executables-have-shebangs + - id: check-json + - id: check-merge-conflict + - id: check-shebang-scripts-are-executable + - id: check-symlinks + - id: check-toml + - id: check-vcs-permalinks + - id: check-xml + - id: check-yaml + - id: debug-statements + - id: destroyed-symlinks + - id: end-of-file-fixer + - id: fix-byte-order-marker + - id: trailing-whitespace + - repo: https://github.com/psf/black + rev: 22.3.0 + hooks: + - id: black + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + - repo: https://github.com/PyCQA/docformatter + rev: v1.5.0 + hooks: + - id: docformatter + additional_dependencies: + - docformatter[tomli] + - repo: https://github.com/PyCQA/pydocstyle + rev: 6.1.1 + hooks: + - id: pydocstyle + exclude: '^tests/' + additional_dependencies: + - pydocstyle[toml] + - repo: https://github.com/Lucas-C/pre-commit-hooks + rev: v1.1.13 + hooks: + - id: insert-license + name: Insert license headers (shell-style comments) + files: '(?:^|/)(?:.*\.(?:py|sh|toml|ya?ml)|Dockerfile|Makefile)$' + exclude: '(?:^|/)\..+|^docs/Makefile$' + args: + - --detect-license-in-X-top-lines=15 + - --license-filepath + - LICENSES/.license_header.txt + - --comment-style + - '#' + - id: insert-license + name: Insert license headers (XML-style comments) + files: '\.(?:html|md|xml)$' + exclude: '(?:^|/)\..+' + args: + - --detect-license-in-X-top-lines=15 + - --license-filepath + - LICENSES/.license_header.txt + - --comment-style + - '' + - id: insert-license + name: Insert license headers (C-style comments) + files: '\.(?:css|js|ts)$' + exclude: '(?:^|/)\..+' + args: + - --detect-license-in-X-top-lines=15 + - --license-filepath + - LICENSES/.license_header.txt + - --comment-style + - '/*| *| */' + - id: insert-license + name: Insert license headers (reST comments) + files: '\.rst$' + exclude: '(?:^|/)\..+' + args: + - --detect-license-in-X-top-lines=15 + - --license-filepath + - LICENSES/.license_header.txt + - --comment-style + - '..| |' + - repo: https://github.com/fsfe/reuse-tool + rev: v1.0.0 + hooks: + - id: reuse + - repo: https://github.com/qoomon/git-conventional-commits + rev: v2.1.1 + hooks: + - id: conventional-commits diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..afec1ad --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,161 @@ + + +# Contributing + +Thanks for your interest in our project. Contributions are always welcome! + +We are committed to fostering a welcoming, respectful, and harassment-free +environment. Be kind! + +If you have questions, ideas or want to report a bug, feel free to [open an +issue]. Or go ahead and [open a pull request] to contribute code. In order to +reduce the burden on our maintainers, please make sure that your code follows +our style guidelines outlined below. + + +[open an issue]: + https://github.com/DSD-DBS/raillabel-providerkit/issues +[open a pull request]: + https://github.com/DSD-DBS/raillabel-providerkit/pulls + +## Developing + +We recommend that you +[develop inside of a virtual environment](README.md#installation). After you +have set it up, simply run the unit tests to verify that everything is set up +correctly: + +```zsh +pytest +``` + +We additionally recommend that you set up your editor / IDE as follows. + +- Indent with 4 spaces per level of indentation + +- Maximum line length of 79 (add a ruler / thin line / highlighting / ...) + +- _If you use Visual Studio Code_: Consider using a platform which supports + third-party language servers more easily, and continue with the next point. + + Otherwise, set up the editor to run `black`, `pylint` and `mypy` when saving. + To enable automatic import sorting with `isort`, add the following to your + `settings.json`: + + ```json + "[python]": { + "editor.codeActionsOnSave": { + "source.organizeImports": true + } + } + ``` + + Note that the Pylance language server is not recommended, as it occasionally + causes false-positive errors for perfectly valid code. + +- _If you do not use VSC_: Set up your editor to use the [python-lsp-server], + and make sure that the relevant plugins are installed. You can install + everything that's needed into the virtualenv with pip: + + [python-lsp-server]: https://github.com/python-lsp/python-lsp-server + + ```zsh + pip install "python-lsp-server[pylint]" python-lsp-black pyls-isort pylsp-mypy + ``` + + This will provide as-you-type linting as well as automatic formatting on + save. Language server clients are available for a wide range of editors, from + Vim/Emacs to PyCharm/IDEA. + +## Code style + +We base our code style on a modified version of the +[Google style guide for Python code](https://google.github.io/styleguide/pyguide.html). +The key differences are: + +- **Docstrings**: The [Numpy style guide] applies here. + + [numpy style guide]: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + + When writing docstrings for functions, use the imperative style, as per + [PEP-257]). For example, write "Do X and Y" instead of "Does X and Y". + + [pep-257]: https://peps.python.org/pep-0257/ + +- **Overridden methods**: If the documentation did not change from the base + class (i.e. the base class' method's docstring still applies without + modification), do not add a short docstring รก la "See base class". This lets + automated tools pick up the full base class docstring instead, and is + therefore more useful in IDEs etc. + +- **Linting**: Use [pylint] for static code analysis, and [mypy] for static + type checking. + + [pylint]: https://github.com/PyCQA/pylint + [mypy]: https://github.com/python/mypy + +- **Formatting**: Use [black] as code auto-formatter. The maximum line length + is 79, as per [PEP-8]. This setting should be automatically picked up from + the `pyproject.toml` file. The reason for the shorter line length is that it + avoids wrapping and overflows in side-by-side split views (e.g. diffs) if + there's also information displayed to the side of it (e.g. a tree view of the + modified files). + + [black]: https://github.com/psf/black + [pep-8]: https://www.python.org/dev/peps/pep-0008/ + + Be aware of the different line length of 72 for docstrings. We currently do + not have a satisfactory solution to automatically apply or enforce this. + + Note that, while you're encouraged to do so in general, it is not a hard + requirement to break up long strings into smaller parts. Additionally, never + break up strings that are presented to the user in e.g. log messages, as that + makes it significantly harder to grep for them. + + Use [isort] for automatic sorting of imports. Its settings should + automatically be picked up from the `pyproject.toml` file as well. + + [isort]: https://github.com/PyCQA/isort + +- **Typing**: We do not make an exception for `typing` imports. Instead of + writing `from typing import SomeName`, use `import typing as t` and access + typing related classes like `t.TypedDict`. + + + + Use the new syntax and classes for typing introduced with Python 3.10 and available using + `from __future__ import annotations` since Python 3.8. + + Be aware however that this only works in the context of annotations; the code + still needs to run on Python 3.8! This means that in some (rare) cases, you _must_ use the + old-style type hints. + + - Instead of `t.Tuple`, `t.List` etc. use the builtin classes `tuple`, `list` + etc. + - For classes that are not builtin (e.g. `Iterable`), + `import collections.abc as cabc` and then use them like `cabc.Iterable`. + - Use [PEP-604-style unions], e.g. `int | float` instead of + `t.Union[int, float]`. + - Use `... | None` (with `None` always as the last union member) instead of + `t.Optional[...]` and always explicitly annotate where `None` is possible. + + [pep-604-style unions]: https://www.python.org/dev/peps/pep-0604/ + +- **Python style rules**: For conflicting parts, the [Black code style] wins. + If you have set up black correctly, you don't need to worry about this though + :) + + [black code style]: + https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html + +- When working with `dict`s, consider using `t.TypedDict` instead of a more + generic `dict[str, float|int|str]`-like annotation where possible, as the + latter is much less precise (often requiring additional `assert`s or + `isinstance` checks to pass) and can grow unwieldy very quickly. + +- Prefer `t.NamedTuple` over `collections.namedtuple`, because the former uses + a more convenient `class ...:` syntax and also supports type annotations. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/LICENSES/.license_header.txt b/LICENSES/.license_header.txt new file mode 100644 index 0000000..c3fb022 --- /dev/null +++ b/LICENSES/.license_header.txt @@ -0,0 +1,2 @@ +Copyright DB Netz AG and contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/LICENSES/Apache-2.0.txt b/LICENSES/Apache-2.0.txt new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSES/Apache-2.0.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/LICENSES/CC0-1.0.txt b/LICENSES/CC0-1.0.txt new file mode 100644 index 0000000..0e259d4 --- /dev/null +++ b/LICENSES/CC0-1.0.txt @@ -0,0 +1,121 @@ +Creative Commons Legal Code + +CC0 1.0 Universal + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS + PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM + THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED + HEREUNDER. + +Statement of Purpose + +The laws of most jurisdictions throughout the world automatically confer +exclusive Copyright and Related Rights (defined below) upon the creator +and subsequent owner(s) (each and all, an "owner") of an original work of +authorship and/or a database (each, a "Work"). + +Certain owners wish to permanently relinquish those rights to a Work for +the purpose of contributing to a commons of creative, cultural and +scientific works ("Commons") that the public can reliably and without fear +of later claims of infringement build upon, modify, incorporate in other +works, reuse and redistribute as freely as possible in any form whatsoever +and for any purposes, including without limitation commercial purposes. +These owners may contribute to the Commons to promote the ideal of a free +culture and the further production of creative, cultural and scientific +works, or to gain reputation or greater distribution for their Work in +part through the use and efforts of others. + +For these and/or other purposes and motivations, and without any +expectation of additional consideration or compensation, the person +associating CC0 with a Work (the "Affirmer"), to the extent that he or she +is an owner of Copyright and Related Rights in the Work, voluntarily +elects to apply CC0 to the Work and publicly distribute the Work under its +terms, with knowledge of his or her Copyright and Related Rights in the +Work and the meaning and intended legal effect of CC0 on those rights. + +1. Copyright and Related Rights. A Work made available under CC0 may be +protected by copyright and related or neighboring rights ("Copyright and +Related Rights"). Copyright and Related Rights include, but are not +limited to, the following: + + i. the right to reproduce, adapt, distribute, perform, display, + communicate, and translate a Work; + ii. moral rights retained by the original author(s) and/or performer(s); +iii. publicity and privacy rights pertaining to a person's image or + likeness depicted in a Work; + iv. rights protecting against unfair competition in regards to a Work, + subject to the limitations in paragraph 4(a), below; + v. rights protecting the extraction, dissemination, use and reuse of data + in a Work; + vi. database rights (such as those arising under Directive 96/9/EC of the + European Parliament and of the Council of 11 March 1996 on the legal + protection of databases, and under any national implementation + thereof, including any amended or successor version of such + directive); and +vii. other similar, equivalent or corresponding rights throughout the + world based on applicable law or treaty, and any national + implementations thereof. + +2. Waiver. To the greatest extent permitted by, but not in contravention +of, applicable law, Affirmer hereby overtly, fully, permanently, +irrevocably and unconditionally waives, abandons, and surrenders all of +Affirmer's Copyright and Related Rights and associated claims and causes +of action, whether now known or unknown (including existing as well as +future claims and causes of action), in the Work (i) in all territories +worldwide, (ii) for the maximum duration provided by applicable law or +treaty (including future time extensions), (iii) in any current or future +medium and for any number of copies, and (iv) for any purpose whatsoever, +including without limitation commercial, advertising or promotional +purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each +member of the public at large and to the detriment of Affirmer's heirs and +successors, fully intending that such Waiver shall not be subject to +revocation, rescission, cancellation, termination, or any other legal or +equitable action to disrupt the quiet enjoyment of the Work by the public +as contemplated by Affirmer's express Statement of Purpose. + +3. Public License Fallback. Should any part of the Waiver for any reason +be judged legally invalid or ineffective under applicable law, then the +Waiver shall be preserved to the maximum extent permitted taking into +account Affirmer's express Statement of Purpose. In addition, to the +extent the Waiver is so judged Affirmer hereby grants to each affected +person a royalty-free, non transferable, non sublicensable, non exclusive, +irrevocable and unconditional license to exercise Affirmer's Copyright and +Related Rights in the Work (i) in all territories worldwide, (ii) for the +maximum duration provided by applicable law or treaty (including future +time extensions), (iii) in any current or future medium and for any number +of copies, and (iv) for any purpose whatsoever, including without +limitation commercial, advertising or promotional purposes (the +"License"). The License shall be deemed effective as of the date CC0 was +applied by Affirmer to the Work. Should any part of the License for any +reason be judged legally invalid or ineffective under applicable law, such +partial invalidity or ineffectiveness shall not invalidate the remainder +of the License, and in such case Affirmer hereby affirms that he or she +will not (i) exercise any of his or her remaining Copyright and Related +Rights in the Work or (ii) assert any associated claims and causes of +action with respect to the Work, in either case contrary to Affirmer's +express Statement of Purpose. + +4. Limitations and Disclaimers. + + a. No trademark or patent rights held by Affirmer are waived, abandoned, + surrendered, licensed or otherwise affected by this document. + b. Affirmer offers the Work as-is and makes no representations or + warranties of any kind concerning the Work, express, implied, + statutory or otherwise, including without limitation warranties of + title, merchantability, fitness for a particular purpose, non + infringement, or the absence of latent or other defects, accuracy, or + the present or absence of errors, whether or not discoverable, all to + the greatest extent permissible under applicable law. + c. Affirmer disclaims responsibility for clearing rights of other persons + that may apply to the Work or any use thereof, including without + limitation any person's Copyright and Related Rights in the Work. + Further, Affirmer disclaims responsibility for obtaining any necessary + consents, permissions or other rights required for any use of the + Work. + d. Affirmer understands and acknowledges that Creative Commons is not a + party to this document and has no duty or obligation with respect to + this CC0 or use of the Work. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef56587 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ + + +# RailLabel + + +![image](https://github.com/DSD-DBS/raillabel/actions/workflows/build-test-publish.yml/badge.svg) +![image](https://github.com/DSD-DBS/raillabel/actions/workflows/lint.yml/badge.svg) + +A devkit for working with recorded and annotated train ride data from Deutsche Bahn. + +# Documentation + + +Read the [full documentation on Github pages](https://dsd-dbs.github.io/raillabel). + +# Installation + +You can install the latest released version directly from PyPI. + +```zsh +pip install raillabel +``` + +To set up a development environment, clone the project and install it into a +virtual environment. + +```zsh +git clone https://github.com/DSD-DBS/raillabel +cd raillabel +python -m venv .venv + +source .venv/bin/activate.sh # for Linux / Mac +.venv\Scripts\activate # for Windows + +pip install -U pip pre-commit +pip install -e '.[docs,test]' +pre-commit install +``` + +# Contributing + +We'd love to see your bug reports and improvement suggestions! Please take a +look at our [guidelines for contributors](CONTRIBUTING.md) for details. + +# Licenses + +This project is compliant with the +[REUSE Specification Version 3.0](https://git.fsfe.org/reuse/docs/src/commit/d173a27231a36e1a2a3af07421f5e557ae0fec46/spec.md). + +Copyright DB Netz AG, licensed under Apache 2.0 (see full text in +[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt)) + +Dot-files are licensed under CC0-1.0 (see full text in +[LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt)) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..fdfe666 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,23 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: CC0-1.0 + +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..ab614db --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,37 @@ +@ECHO OFF +REM Copyright DB Netz AG and contributors +REM SPDX-License-Identifier: CC0-1.0 + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/github-logo.svg b/docs/source/_static/github-logo.svg new file mode 100644 index 0000000..a407b96 --- /dev/null +++ b/docs/source/_static/github-logo.svg @@ -0,0 +1,9 @@ + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..c2c8d9f --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,120 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: Apache-2.0 +"""Configuration file for Sphinx.""" + + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../..")) + +import raillabel_providerkit + +# -- Project information ----------------------------------------------------- + +try: + import tomllib +except ImportError: + import tomli as tomllib # type: ignore[no-redef] +with open("../../pyproject.toml", "rb") as f: + _metadata = tomllib.load(f)["project"] + +project = "RailLabel Providerkit" +pypi = "raillabel-providerkit" +author = _metadata["authors"][0]["name"] +copyright = f"{author} and the {_metadata['name']} contributors" +license = _metadata["license"]["text"] +install_requirements = _metadata["dependencies"] +python_requirement = _metadata["requires-python"] + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.coverage", + "sphinx.ext.intersphinx", + "sphinx.ext.napoleon", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +# exclude_patterns = [] + + +# -- General information about the project ----------------------------------- + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# The full version, including alpha/beta/rc tags. +version = raillabel_providerkit.__version__ +rst_epilog = """ +.. |Project| replace:: {project} +.. |Version| replace:: {version} +""".format( + project=project, version=version +) + + +# -- Options for copy-button ------------------------------------------------- +copybutton_here_doc_delimiter = "EOT" +copybutton_line_continuation_character = "\\" + + +# -- Options for auto-doc ---------------------------------------------------- +autoclass_content = "class" + + +# -- Options for napoleon ---------------------------------------------------- +napoleon_google_docstring = False +napoleon_include_init_with_doc = True + + +# -- Options for Intersphinx output ------------------------------------------ +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +html_theme = "furo" +html_theme_options = { + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/DSD-DBS/raillabel", + "html": '', + "class": "", + }, + ], +} + + +# -- Extra options for Furo theme -------------------------------------------- + +pygments_style = "tango" +pygments_dark_style = "monokai" + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/docs/source/howto.rst b/docs/source/howto.rst new file mode 100644 index 0000000..5cef8ca --- /dev/null +++ b/docs/source/howto.rst @@ -0,0 +1,20 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +.. _howtos: + +******* +How Tos +******* + +In this section you can view dedicated tutorial-notebooks of key +features. + + +.. toctree:: + :maxdepth: 4 + :caption: How tos: + :glob: + + howtos/* diff --git a/docs/source/howtos/1 Validating Annotation Files.rst b/docs/source/howtos/1 Validating Annotation Files.rst new file mode 100644 index 0000000..52d4a31 --- /dev/null +++ b/docs/source/howtos/1 Validating Annotation Files.rst @@ -0,0 +1,75 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +============================= +1 Validating Annotation Files +============================= + +Some annotation files might not fit the valid schema, depending on their source and editing history. To check whether a JSON file is a valid RailLabel annotation file, the raillabel.validate() method can be used. This checks the JSON file against a given schema and returns whether the data is valid and any potential incompatibilities with the schema. + +.. code-block:: python + + import raillabel + + valid_data = { + "openlabel": { + "metadata": { + "schema_version": "1.0.0" + } + } + } + + raillabel.validate(valid_data) + +.. code-block:: python + + Returns: (True, []) + +.. code-block:: python + + import raillabel + + invalid_data = { + "openlabel": { + "metadata": { + "schema_version": "1.0.0" + }, + "invalid_field": "foo" + } + } + + raillabel.validate(invalid_data) + +.. code-block:: python + + Returns: (False, ["$.openlabel: Additional properties are not allowed ('invalid_field' was unexpected)"]) + +By default, the OpenLABEL JSON schema is used for validation. However, the method can validate data with any schema. + +.. code-block:: python + + import raillabel + + data = { + "openlabel": { + "metadata": { + "schema_version": "2.0.0" + } + } + } + + raillabel.validate(data, "path/to/schema.json") + +The method returns a tuple of two elements. The first element is a boolean marking if the data validates against the schema. The second is a list of strings with each string being an error in the data. This example shows how to present the results of the method to a user. + +.. code-block:: python + + is_data_valid, warnings = raillabel.validate(data) + + if is_data_valid: + do_something() + + else: + for w in warnings: + print(w) diff --git a/docs/source/howtos/2 Loading Annotation Files.rst b/docs/source/howtos/2 Loading Annotation Files.rst new file mode 100644 index 0000000..75539b4 --- /dev/null +++ b/docs/source/howtos/2 Loading Annotation Files.rst @@ -0,0 +1,25 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +========================== +2 Loading Annotation Files +========================== + +Loading annotation files into a raillabel.Scene is done with ``raillabel.load()``. + +.. code-block:: python + + import raillabel + scene = raillabel.load('path/to/file.json') + +The method can itself identify if the file is from a supported format and then choose the correct loader-class. + +Validation +========== +If the data should be validated before beeing loaded, the ``validate`` parameter can be set to True. If the data is not valid, a ``raillabel.SchemaError`` is raised with all errors included. + +.. code-block:: python + + import raillabel + scene = raillabel.load('path/to/file.json', validate=True) diff --git a/docs/source/howtos/3 Saving Annotation Files.rst b/docs/source/howtos/3 Saving Annotation Files.rst new file mode 100644 index 0000000..e79d4ca --- /dev/null +++ b/docs/source/howtos/3 Saving Annotation Files.rst @@ -0,0 +1,32 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +========================= +3 Saving Annotation Files +========================= + +If changes have been made to an annotation file or a file should be copied, it can be saved via the ``raillabel.save()`` method. + +.. code-block:: python + + import raillabel + + scene = raillabel.load('path/to/file.json') + scene.frames['0'].stream_stamps['lidar'].timestamp += 37 + raillabel.save(scene, 'path/to/file.json') + +By default, the JSON file is saved as compact as possible with no linebreaks or indents. This can be changed by setting ``prettify_json=True`` as an argument. The indent size used is 4 spaces. + +Validation +========== + +If the data should be validated after beeing saved, the ``validate`` parameter can be set to True. If the data is not valid, a ``raillabel.SchemaError`` is raised with all errors included and the data is not saved. + +.. code-block:: python + + import raillabel + + scene = raillabel.load('path/to/file.json') + scene.frames['0'].stream_stamps['lidar'].timestamp += 37 + raillabel.save(scene, 'path/to/file.json', validate=True) diff --git a/docs/source/howtos/4 Filtering Scenes.rst b/docs/source/howtos/4 Filtering Scenes.rst new file mode 100644 index 0000000..277da5c --- /dev/null +++ b/docs/source/howtos/4 Filtering Scenes.rst @@ -0,0 +1,50 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +================== +4 Filtering Scenes +================== + +The annotations of a scene can be filtered by many criteria. This functionality is provided by ``raillabel.filter()``. This method takes a scene and filter arguments and returns a copy of the scene with filters applied. + +.. code-block:: python + + import raillabel + import decimal + + scene = raillabel.load('path/to/file.json') + + scene_with_only_trains = raillabel.filter( + scene, + include_object_types=['train'] + ) + scene_without_bboxs = raillabel.filter( + scene, + exclude_annotation_types=['bbox'] + ) + cut_scene_with_only_red_trains = raillabel.filter( + scene, + start_timestamp=decimal.Decimal('1587349200.004200000'), + exclude_frames=[4, 2], + include_object_types=['train'], + include_attributes={ + 'color': 'red' + } + ) + scene_with_annotations_with_an_attribute = raillabel.filter( + scene, + include_attributes={ # All annotations with the color + 'color': None # attribute will be included, + } # regardless of color value. + ) + +Most filter categories have an include and exclude parameter (i.e ``include_object_types`` and ``exclude_object_types``). When include is set, all annotations, that meet the criterium are *included* into the filtered scene. Excluded parameters are *excluded* from the scene. These two parameters are mutually exclusive and can not both be set. + +.. code-block:: python + + invalid_scene = raillabel.filter( + scene, + include_object_types=['person'], # Will raise a ValueError due + exclude_object_types=['train'] # to mutual exclusivity. + ) diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d24347d --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,45 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +***************************** +Welcome to the documentation! +***************************** + +Python RailLabel Development-Kit +================================ + +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black + :alt: Black + +**Date**: |today| **Version**: |Version| + +Description +----------- +This library is designed to assist in the handling of the sensor annotations of Deutsche Bahn in the OpenLABEL data format. Common usage for the library: + +* fetching specific information from annotation files +* filtering for specific frames, annotations or objects +* editing annotation files + +If you want a quickstart at how to use this package, head right into the +:ref:`how-tos section `. + +.. toctree:: + :caption: Introduction + :maxdepth: 4 + + intro + +.. toctree:: + :caption: Tutorials + :titlesonly: + + howto + +.. toctree:: + :caption: Modules + :maxdepth: 4 + + code/modules diff --git a/docs/source/intro.rst b/docs/source/intro.rst new file mode 100644 index 0000000..a51ab69 --- /dev/null +++ b/docs/source/intro.rst @@ -0,0 +1,35 @@ +.. + Copyright DB Netz AG and contributors + SPDX-License-Identifier: Apache-2.0 + +Motivation +---------- + +Working with our own data has brought up the need to interact with the annotations programmatically. The annotation data is stored in .json files in the `ASAM OpenLABEL annotation `_ format, an emerging industry standard targeted towards the automotive sector. But as a standard it is designed very inclusively, which makes it overloaded for our limited use cases. We therefore decided to create a submodel called "RailLabel" with a corresponding devkit for easier interaction with the data. The example below shows a comparison between a purely JSON based approach compared to the devkit. + +With JSON only: + +.. code-block:: python + + import json + + with open('path/to/file.json', 'r') as data_file: + scene = json.load(data_file) + + scene['openlabel']['frames']['0']['frame_properties']['streams']['lidar']['stream_properties']['stream_sync']['timestamp'] += 37 + + with open('path/to/other_file.json', 'w') as data_file: + json.dump(scene, data_file) + +With RailLabel: + +.. code-block:: python + + import raillabel + + scene = raillabel.load('path/to/file.json') + scene.frames['0'].streams['lidar'].timestamp += 37 + raillabel.save(scene, 'path/to/other_file.json') + + +The devkit also includes other functionality like validating data against a schema and filtering the annotations. diff --git a/git-conventional-commits.json b/git-conventional-commits.json new file mode 100644 index 0000000..1da947a --- /dev/null +++ b/git-conventional-commits.json @@ -0,0 +1,20 @@ +{ + "convention" : { + "commitTypes": [ + "build", + "chore", + "ci", + "docs", + "feat", + "fix", + "merge", + "perf", + "refactor", + "revert", + "test", + + "lint" + ], + "commitScopes": [] + } +} diff --git a/git-conventional-commits.json.license b/git-conventional-commits.json.license new file mode 100644 index 0000000..1b58a49 --- /dev/null +++ b/git-conventional-commits.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright DB Netz AG and the raillabel-providerkit contributors +SPDX-License-Identifier: Apache-2.0 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..6e23f98 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,186 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: Apache-2.0 + +[build-system] +requires = [ + "setuptools>=64", + "setuptools_scm[toml]>=3.4", + "wheel" +] +build-backend = "setuptools.build_meta" + +[project] +dynamic = ["version"] + +name = "raillabel-providerkit-providerkit" +description = "A devkit for working with recorded and annotated train ride data from Deutsche Bahn." +readme = "README.md" +requires-python = ">=3.8, <3.12" +license = { text = "Apache-2.0" } +authors = [ + { name = "DB Netz AG" }, +] +keywords = [] +classifiers = [ + "Development Status :: 1 - Planning", + "License :: OSI Approved :: Apache Software License", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", +] +dependencies = [ + "jsonschema>=4.4.0", + "fastjsonschema>=2.16.2" +] + +[project.urls] +Homepage = "https://github.com/DSD-DBS/raillabel-providerkit-providerkit" +Documentation = "https://dsd-dbs.github.io/raillabel-providerkit-providerkit" + +[project.optional-dependencies] +docs = [ + "furo", + "sphinx", + "sphinx-copybutton", + "tomli; python_version<'3.11'", +] + +test = [ + "pytest", + "pytest-cov", + "json5" +] + +[tool.black] +line-length = 100 +target-version = ["py38"] +force-exclude = "tests/" + +[tool.docformatter] +wrap-descriptions = 72 +wrap-summaries = 79 + +[tool.isort] +profile = 'black' +line_length = 100 + +[tool.mypy] +check_untyped_defs = true +no_implicit_optional = true +show_error_codes = true +warn_redundant_casts = true +warn_unreachable = true +python_version = "3.8" + +[[tool.mypy.overrides]] +module = ["tests.*"] +allow_incomplete_defs = true +allow_untyped_defs = true + +[[tool.mypy.overrides]] +# Untyped third party libraries +module = [ + # ... +] +ignore_missing_imports = true + +[tool.pydocstyle] +convention = "numpy" +add-select = [ + "D212", # Multi-line docstring summary should start at the first line + "D402", # First line should not be the functions "signature" + "D417", # Missing argument descriptions in the docstring +] +add-ignore = [ + "D100", # Missing docstring in public module + "D201", # No blank lines allowed before function docstring # auto-formatting + "D202", # No blank lines allowed after function docstring # auto-formatting + "D203", # 1 blank line required before class docstring # auto-formatting + "D204", # 1 blank line required after class docstring # auto-formatting + "D209", # Multi-line docstring closing quotes should be on a separate line + "D211", # No blank lines allowed before class docstring # auto-formatting + "D213", # Multi-line docstring summary should start at the second line +] + +[tool.pylint.master] +max-line-length = 100 + +[tool.pylint.messages_control] +disable = [ + "arguments-renamed", + "global-statement", + "invalid-name", + "no-else-return", # using else returns is more readible imo + "protected-access", # class comparisons raised as false positive + "redefined-builtin", # the domain is full of builtin-names (object, type, format, ...) + "too-few-public-methods", # does not contribute to code quality imo + "too-many-arguments", # 6 as a limit is too low + "too-many-instance-attributes", # classes mirror OpenLABEL, therefore the number of fields is set + "unidiomatic-typecheck", # type() is necessary in some cases + "unspecified-encoding", # default encoding is sufficient in all cases + "unsupported-membership-test", # raise false positives for dicts + "global-variable-not-assigned", # raises false positive when global variable is a dict and items are assigned + + # Auto-formatting + "bad-indentation", + "inconsistent-quotes", + "missing-final-newline", + "missing-class-docstring", + "missing-function-docstring", + "missing-module-docstring", + "mixed-line-endings", + "multiple-imports", + "multiple-statements", + "trailing-newlines", + "trailing-whitespace", + "unexpected-line-ending-format", + "ungrouped-imports", + "wrong-import-order", + "wrong-import-position", + + # Handled by mypy + "arguments-differ", + "assignment-from-no-return", + "import-error", + "missing-kwoa", + "no-member", + "no-value-for-parameter", + "redundant-keyword-arg", + "signature-differs", + "syntax-error", + "too-many-function-args", + "unbalanced-tuple-unpacking", + "undefined-variable", + "unexpected-keyword-arg", +] +enable = [ + "c-extension-no-member", + "deprecated-pragma", + "use-symbolic-message-instead", + "useless-suppression", +] + +[tool.pytest.ini_options] +addopts = """ + --strict-config + --strict-markers +""" +testpaths = ["tests"] +xfail_strict = true + +[tool.setuptools] +platforms = ["any"] +zip-safe = false + +[tool.setuptools.package-data] +"*" = ["py.typed"] + +[tool.setuptools.packages.find] +exclude = ["LICENSES"] + +[tool.setuptools_scm] +# This section must exist for setuptools_scm to work diff --git a/tests/master_test.py b/tests/master_test.py new file mode 100644 index 0000000..a4968d8 --- /dev/null +++ b/tests/master_test.py @@ -0,0 +1,17 @@ +# Copyright DB Netz AG and contributors +# SPDX-License-Identifier: Apache-2.0 + +import os +import pathlib + +import pytest + +# Executes the test +os.system("clear") +pytest.main( + [ + str(pathlib.Path(__file__).parent), + "--disable-pytest-warnings", + "--cache-clear", + ] +)