{"id":17277896,"url":"https://github.com/abravalheri/ini2toml","last_synced_at":"2025-04-04T18:05:54.637Z","repository":{"id":37956518,"uuid":"416089353","full_name":"abravalheri/ini2toml","owner":"abravalheri","description":"Automatically conversion of `.ini/.cfg` files to TOML equivalents","archived":false,"fork":false,"pushed_at":"2025-03-24T12:11:49.000Z","size":489,"stargazers_count":62,"open_issues_count":5,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T17:11:13.247Z","etag":null,"topics":["cfg-files","ini","pep621","setuptools","toml"],"latest_commit_sha":null,"homepage":"https://ini2toml.readthedocs.io/en/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abravalheri.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-11T21:16:56.000Z","updated_at":"2025-03-25T09:37:43.000Z","dependencies_parsed_at":"2023-09-25T22:31:11.994Z","dependency_job_id":"6135c088-b5f9-43e0-a91e-9f0990ac78f3","html_url":"https://github.com/abravalheri/ini2toml","commit_stats":{"total_commits":430,"total_committers":7,"mean_commits":61.42857142857143,"dds":"0.11395348837209307","last_synced_commit":"5e6e000519d9ad9f24634c9149d479ddaa36e50f"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abravalheri%2Fini2toml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abravalheri%2Fini2toml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abravalheri%2Fini2toml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abravalheri%2Fini2toml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abravalheri","download_url":"https://codeload.github.com/abravalheri/ini2toml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226213,"owners_count":20904465,"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":["cfg-files","ini","pep621","setuptools","toml"],"created_at":"2024-10-15T09:10:19.319Z","updated_at":"2025-04-04T18:05:54.608Z","avatar_url":"https://github.com/abravalheri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. These are examples of badges you might want to add to your README:\n   please update the URLs accordingly\n\n    .. image:: https://img.shields.io/conda/vn/conda-forge/ini2toml.svg\n        :alt: Conda-Forge\n        :target: https://anaconda.org/conda-forge/ini2toml\n    .. image:: https://pepy.tech/badge/ini2toml/month\n        :alt: Monthly Downloads\n        :target: https://pepy.tech/project/ini2toml\n    .. image:: https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Twitter\n        :alt: Twitter\n        :target: https://twitter.com/ini2toml\n\n.. image:: https://api.cirrus-ci.com/github/abravalheri/ini2toml.svg?branch=main\n    :alt: Built Status\n    :target: https://cirrus-ci.com/github/abravalheri/ini2toml\n.. image:: https://readthedocs.org/projects/ini2toml/badge/?version=latest\n    :alt: ReadTheDocs\n    :target: https://ini2toml.readthedocs.io\n.. image:: https://img.shields.io/coveralls/github/abravalheri/ini2toml/main.svg\n    :alt: Coveralls\n    :target: https://coveralls.io/r/abravalheri/ini2toml\n.. image:: https://img.shields.io/pypi/v/ini2toml.svg\n    :alt: PyPI-Server\n    :target: https://pypi.org/project/ini2toml/\n.. image:: https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold\n    :alt: Project generated with PyScaffold\n    :target: https://pyscaffold.org/\n\n|\n\n========\nini2toml\n========\n\n\n    Automatically translates |ini_cfg|_ files into TOML_\n\n.. important:: This project is **experimental** and under active development\n   Issue reports and contributions are very welcome.\n\n\nDescription\n===========\n\nThe original purpose of this project is to help migrating ``setup.cfg`` files\nto `PEP 621`_, but by extension it can also be used to convert any compatible |ini_cfg|_\nfile to TOML_.\n\nPlease notice, the provided |ini_cfg|_ files should follow the same syntax\nsupported by Python's |ConfigParser|_ library (here referred to as INI syntax)\nand more specifically abide by |ConfigUpdater|_ restrictions (e.g., no\ninterpolation or repeated fields).\n\n\nUsage\n=====\n\n``ini2toml`` comes in two flavours: *\"lite\"* and *\"full\"*. The \"lite\"\nflavour will create a TOML document that does not contain any of the comments\nfrom the original |ini_cfg| file. On the other hand, the \"full\" flavour\nwill make an extra effort to translate these comments into a TOML-equivalent\n(please notice sometimes this translation is not perfect, so it is always good\nto check the TOML document afterwards).\n\nTo get started, you need to install the package, which can be easily done\nusing |pipx|_:\n\n.. code-block:: bash\n\n    $ pipx install 'ini2toml[lite]'\n    # OR\n    $ pipx install 'ini2toml[full]'\n\nNow you can use ``ini2toml`` as a command line tool:\n\n.. code-block:: bash\n\n    # in you terminal\n    $ ini2toml --help\n    $ ini2toml path/to/ini/or/cfg/file\n\nYou can also use ``ini2toml`` in your Python scripts or projects:\n\n.. code-block:: python\n\n    # in your python code\n    from ini2toml.api import Translator\n\n    profile_name = \"setup.cfg\"\n    toml_str = Translator().translate(original_contents_str, profile_name)\n\nTo do so, don't forget to add it to your `virtual environment`_ or specify it as a\n`project dependency`_.\n\nNote that the class ``Translator`` will try to guess which flavour to use based\non the available installed dependencies. If you need something more\ndeterministic, consider using ``LiteTranslator`` and ``FullTranslator``,\nor explicitly specifying the ``ini_loads_fn`` and ``toml_dumps_fn`` keyword\narguments in the constructor.\n\nMore details about ``ini2toml`` and its Python API can be found in `our docs`_.\n\n\nLimitations\n===========\n\n``ini2toml`` will try its best to create good quality translations from\n``.ini/.cfg`` into ``.toml`` files. However the tool comes with a set of\nwell known limitations:\n\n* Although ``ini2toml`` attempts to keep the same order/sequence as the original\n  information was written, sometimes that is not compatible with the TOML\n  syntax, and things end up moving around a bit.\n\n* ``ini2toml`` uses `ConfigParser`_ + `tomli-w`_ for implementing the *\"lite\"* flavour\n  and `ConfigUpdater`_ + `tomlkit`_ for implementing the *\"full\"* flavour.\n  Therefore it inherits the limitations from those libraries (please check\n  their documentation for more information). For example:\n\n  * `ConfigUpdater`_, will have trouble to parse interpolations and the related\n    escaping sequence (``%%``) (in this respect, it behaves more similarly to\n    ``RawConfigParser`` than ``ConfigParser``).\n\n  * `tomli-w`_ is not very flexible regarding formatting and will have trouble\n    with multi-line strings.\n\n* ``ini2toml`` *expects the input to be valid* and will not perform extensive\n  checks on the provided document. If something in the output is not working as you would\n  expect, it might be a good idea to check the input.\n\n* ``.ini/.cfg`` files are used in a plethora of use cases and it is impossible\n  to cover all of them in a single code base. Even when considering\n  ``setup.cfg``, there are many packages that define different sections in the\n  document in addition to the basic definition by ``setuptools``.\n  Because of that ``ini2toml``, adopts a \"best-effort\" approach, that might not\n  correspond to what you expect. If that is the case please consider\n  contributing or creating your own `plugin`_.\n\n* The translation procedure analyse only the given input. If the original\n  ``.ini/.cfg`` file contains references to other files, or behaves differently\n  depending on the existence/presence of other files and directories, the\n  translation will not take that into consideration.\n\nTherefore it is recommended to double check the output and fix any\nproblems before using the ``.toml`` files in production.\n\n\nCan ``ini2toml`` also translate ``setup.py`` into ``pyproject.toml``?\n=====================================================================\n\nWorking with ``.py`` files is not in the scope of the ``ini2toml`` project,\nand therefore this feature is not implemented.\n\nHowever, you can probably find some tools on PyPI to translate from\n``setup.py`` into ``setup.cfg``, like `setup-py-upgrade`_ and\n`setuptools-py2cfg`_ [#untested]_.\n\nOnce you have ``setup.cfg``, you can use ``ini2toml`` [#setuppy]_.\n\n.. [#untested] Such tools are neither maintained by this project,\n   nor tested for integration by ``ini2toml``.\n   It is best to try some of them out and find the one that works for you.\n   Manual corrections might be needed.\n\n.. [#setuppy] Please note that ``setup.py`` is a very dynamic\n   format and that not everything can be represented in ``setup.cfg`` or\n   ``pyproject.toml``. Indeed, the `setuptools' docs`_ explicitly say that\n   ``setup.py`` can be used in tandem with ``pyproject.toml``: ideally all the\n   declarative metadata goes to ``pyproject.toml``, but you can keep the\n   dynamic bits in ``setup.py``.\n   Remember: ``setup.py`` is a perfectly valid and non deprecated configuration file;\n   what is deprecated is running it as a CLI tool, i.e. ``python setup.py ...``.\n\n\n.. _pyscaffold-notes:\n\n.. tip::\n   If you consider contributing to this project, have a look on our\n   `contribution guides`_.\n\nNote\n====\n\nThis project was initially created in the context of PyScaffold, with the\npurpose of helping migrating existing projects to `PEP 621`_-style\nconfiguration when it is made available on ``setuptools``.\nFor details and usage information on PyScaffold see https://pyscaffold.org/.\n\n\n.. |ini_cfg| replace:: ``.ini/.cfg``\n.. |ConfigParser| replace:: ``ConfigParser``\n.. |ConfigUpdater| replace:: ``ConfigUpdater``\n.. |pipx| replace:: ``pipx``\n\n.. _ConfigParser: https://docs.python.org/3/library/configparser.html\n.. _ConfigUpdater: https://github.com/pyscaffold/configupdater\n.. _contribution guides: https://ini2toml.readthedocs.io/en/latest/contributing.html\n.. _ini_cfg: https://docs.python.org/3/library/configparser.html#supported-ini-file-structure\n.. _our docs: https://ini2toml.readthedocs.io\n.. _PEP 621: https://www.python.org/dev/peps/pep-0621/\n.. _pipx: https://pipx.pypa.io/stable/\n.. _project dependency: https://packaging.python.org/tutorials/managing-dependencies/\n.. _plugin: https://ini2toml.readthedocs.io/en/latest/dev-guide.html#plugins\n.. _setup-py-upgrade: https://pypi.org/project/setup-py-upgrade/\n.. _setuptools-py2cfg: https://pypi.org/project/setuptools-py2cfg/\n.. _setuptools' docs: https://setuptools.pypa.io/en/latest/userguide/quickstart.html#setuppy-discouraged\n.. _TOML: https://toml.io/en/\n.. _TOML library: https://github.com/sdispater/tomlkit\n.. _tomli-w: https://pypi.org/project/tomli-w/\n.. _tomlkit: https://tomlkit.readthedocs.io/en/latest/\n.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabravalheri%2Fini2toml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabravalheri%2Fini2toml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabravalheri%2Fini2toml/lists"}