{"id":13494992,"url":"https://github.com/bobfang1992/pytomlpp","last_synced_at":"2026-03-07T11:03:26.787Z","repository":{"id":40356575,"uuid":"268834889","full_name":"bobfang1992/pytomlpp","owner":"bobfang1992","description":"A python wrapper for tomlplusplus","archived":false,"fork":false,"pushed_at":"2024-09-03T21:04:59.000Z","size":268,"stargazers_count":86,"open_issues_count":3,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-03T01:40:21.598Z","etag":null,"topics":["parser","python","python-wrapper","toml","toml-parser"],"latest_commit_sha":null,"homepage":"https://bobfang1992.github.io/pytomlpp/pytomlpp.html","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobfang1992.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-02T15:13:56.000Z","updated_at":"2024-09-16T22:02:35.000Z","dependencies_parsed_at":"2024-06-18T18:40:15.475Z","dependency_job_id":"7177658a-c531-415c-acc2-e9e0bb1453db","html_url":"https://github.com/bobfang1992/pytomlpp","commit_stats":{"total_commits":198,"total_committers":14,"mean_commits":"14.142857142857142","dds":"0.43939393939393945","last_synced_commit":"8c7b4c391df406b8c1bf0c9c830ca79a5f46bc9b"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobfang1992%2Fpytomlpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobfang1992%2Fpytomlpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobfang1992%2Fpytomlpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobfang1992%2Fpytomlpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobfang1992","download_url":"https://codeload.github.com/bobfang1992/pytomlpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222389507,"owners_count":16976486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["parser","python","python-wrapper","toml","toml-parser"],"created_at":"2024-07-31T19:01:30.167Z","updated_at":"2026-03-07T11:03:26.782Z","avatar_url":"https://github.com/bobfang1992.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# pytomlpp\n\n\n[![Conda Status](https://anaconda.org/conda-forge/pytomlpp/badges/version.svg)](https://anaconda.org/conda-forge/pytomlpp)\n[![PyPI version](https://badge.fury.io/py/pytomlpp.svg)](https://badge.fury.io/py/pytomlpp)\n\nThis is an python wrapper for `toml++` (https://marzer.github.io/tomlplusplus/).\n\nSome points you may want to know before use:\n\n- Using `toml++` means that this module is fully compatible with TOML [v1.0.0](https://toml.io/en/v1.0.0).\n- We convert toml structure to native python data structures (dict/list etc.) when parsing, this is more inline with what `json` module does.\n- The binding is using [pybind11](https://github.com/pybind/pybind11).\n- The project is tested using [toml-test](https://github.com/BurntSushi/toml-test) and [pytest](https://github.com/pytest-dev/pytest).\n- We support all major platforms (Linux, Mac OSX and Windows), for both CPython and Pypy and all recent Python versions. You just need to `pip install` and we have a pre-compiled binaries ready. No need to play with `clang`, `cmake` or any C++ toolchains.\n\n# Example\n\n```\nIn [1]: import pytomlpp\n\nIn [2]: toml_string = 'hello = \"世界\"'\n\nIn [3]: pytomlpp.loads(toml_string)\nOut[3]: {'hello': '世界'}\n\nIn [4]: type(_)\nOut[4]: dict\n\nIn [6]: pytomlpp.dumps({\"你好\": \"world\"})\nOut[6]: '\"你好\" = \"world\"'\n```\n\n# Why bother?\n\nThere are some existing python TOML parsers on the market but from my experience they are implemented purely in python which is a bit slow.\n\n```\nParsing data.toml 1000 times:\n     rtoml:   0.540 s\n  pytomlpp:   0.542 s ( 1.00x)\n     tomli:   2.923 s ( 5.40x)\n     qtoml:   8.748 s (16.18x)\n   tomlkit:  51.608 s (95.49x)\n      toml: Parsing failed. Likely not TOML 1.0.0-compliant.\n```\n\nTest it for yourself using [the benchmark script](benchmark/run.py).\n\n# Installing\n\nWe recommend you to use `pip` to install this package:\n\n```sh\npip install pytomlpp\n```\n\nYou can also use `conda` to install this package, on all common platforms \u0026 python versions.\nIf you have an issue with a package from conda-forge, you can raise an issue on the [feedstock](https://github.com/conda-forge/pytomlpp-feedstock)\n\n```sh\nconda install -c conda-forge pytomlpp\n```\n\nYou can also install from source:\n\n```sh\ngit clone git@github.com:bobfang1992/pytomlpp.git --recurse-submodules=third_party/tomlplusplus --shallow-submodules\ncd pytomlpp\npip install .\n```\n\n# Development\n\n## Prerequisites\n\n- Python 3.8 or higher\n- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)\n- Git (for cloning submodules)\n\n## Setting Up Development Environment\n\n1. **Clone the repository with submodules:**\n\n```sh\ngit clone git@github.com:bobfang1992/pytomlpp.git --recurse-submodules\ncd pytomlpp\n```\n\nIf you already cloned without submodules:\n\n```sh\ngit submodule update --init --recursive\n```\n\n2. **Create a virtual environment (recommended):**\n\n```sh\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. **Install in editable mode with development dependencies:**\n\n```sh\n# Install package in editable mode\npip install -e .\n\n# Install test dependencies\npip install -r tests/requirements.txt\n```\n\n## Building Locally\n\n### Using Modern Build Tools (Recommended)\n\n```sh\n# Install build tool\npip install build\n\n# Build wheel and source distribution\npython -m build\n\n# Output will be in dist/\nls dist/\n# pytomlpp-1.1.0-cp312-cp312-macosx_*.whl\n# pytomlpp-1.1.0.tar.gz\n```\n\n### Using pip (Development)\n\n```sh\n# Install in editable mode (changes to Python code take effect immediately)\npip install -e .\n\n# Rebuild C++ extension after changes\npip install -e . --force-reinstall --no-deps\n```\n\n### Using setup.py (Legacy)\n\n```sh\n# Build extension in-place\npython setup.py build_ext --inplace\n\n# Install\npython setup.py install\n```\n\n## Running Tests\n\n### Run All Tests\n\n```sh\n# From project root\npytest tests/\n\n# With verbose output\npytest tests/ -v\n\n# With coverage\npip install pytest-cov\npytest tests/ --cov=pytomlpp --cov-report=html\n```\n\n### Run Specific Tests\n\n```sh\n# Run only API tests\npytest tests/python-tests/test_api.py\n\n# Run specific test function\npytest tests/python-tests/test_api.py::test_loads_valid_toml_files -v\n\n# Run with keyword matching\npytest tests/ -k \"encode\"\n```\n\n### Test Against toml-test Suite\n\n```sh\ncd tests\n./run.sh  # Runs the official TOML test suite\n```\n\n## Running Benchmarks\n\n```sh\ncd benchmark\npip install -r requirements.txt\npython run.py\n```\n\n## Code Quality\n\n### Format Code (if contributing)\n\n```sh\n# Install pre-commit hooks\npip install pre-commit\npre-commit install\n\n# Run manually\npre-commit run --all-files\n```\n\n### Type Checking\n\n```sh\npip install mypy\nmypy src/pytomlpp/\n```\n\n## Project Structure\n\n```\npytomlpp/\n├── src/\n│   ├── pytomlpp/          # Python package\n│   │   ├── __init__.py\n│   │   ├── _io.py\n│   │   └── _impl.pyi      # Type stubs\n│   ├── pytomlpp.cpp       # C++ bindings (main)\n│   ├── type_casters.cpp   # Python/C++ type conversions\n│   └── encoding_decoding.cpp  # TOML encoding/decoding\n├── include/\n│   └── pytomlpp/          # C++ headers\n├── third_party/\n│   └── tomlplusplus/      # toml++ submodule\n├── tests/\n│   └── python-tests/      # Python test suite\n├── benchmark/             # Performance benchmarks\n├── pyproject.toml         # Project metadata (PEP 621)\n└── setup.py              # C++ extension build config\n```\n\n## Common Issues\n\n### Submodule Not Initialized\n\n```sh\ngit submodule update --init --recursive\n```\n\n### C++ Compilation Errors\n\nMake sure you have a C++17 compatible compiler:\n\n- **Linux**: GCC 7+ or Clang 5+\n- **macOS**: Xcode 10+ (Clang 5+)\n- **Windows**: Visual Studio 2017 or later\n\n### Import Errors After Changes\n\nReinstall in editable mode:\n\n```sh\npip install -e . --force-reinstall --no-deps\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pytest tests/`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines (if available).\n\n## Getting Help\n\n- **Issues**: [GitHub Issues](https://github.com/bobfang1992/pytomlpp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/bobfang1992/pytomlpp/discussions)\n\n---\n\n![Alt](https://repobeats.axiom.co/api/embed/e767bf2c29b32ec317fc591d4cafda263de6c4b0.svg \"Repobeats analytics image\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobfang1992%2Fpytomlpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobfang1992%2Fpytomlpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobfang1992%2Fpytomlpp/lists"}