Metadata-Version: 2.1
Name: ini2toml
Version: 0.13
Summary: Automatically conversion of .ini/.cfg files to TOML equivalents
Home-page: https://github.com/abravalheri/ini2toml/
Author: Anderson Bravalheri
Author-email: andersonbravalheri@gmail.com
License: MPL-2.0
Project-URL: Documentation, https://ini2toml.readthedocs.io/
Project-URL: Source, https://github.com/abravalheri/ini2toml
Project-URL: Tracker, https://github.com/abravalheri/ini2toml/issues
Project-URL: Changelog, https://ini2toml.readthedocs.io/en/latest/changelog.html
Project-URL: Download, https://pypi.org/project/ini2toml/#files
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Description-Content-Type: text/x-rst; charset=UTF-8
License-File: LICENSE.txt
Requires-Dist: packaging >=20.7
Requires-Dist: setuptools >=59.6
Provides-Extra: all
Requires-Dist: configupdater <4,>=3.0.1 ; extra == 'all'
Requires-Dist: tomlkit <2,>=0.10.0 ; extra == 'all'
Requires-Dist: tomli-w <2,>=0.4.0 ; extra == 'all'
Provides-Extra: experimental
Requires-Dist: pyproject-fmt >=0.4.0 ; (python_version >= "3.7") and extra == 'experimental'
Provides-Extra: full
Requires-Dist: configupdater <4,>=3.0.1 ; extra == 'full'
Requires-Dist: tomlkit <2,>=0.10.0 ; extra == 'full'
Requires-Dist: importlib-metadata ; (python_version < "3.8") and extra == 'full'
Provides-Extra: lite
Requires-Dist: tomli-w <2,>=0.4.0 ; extra == 'lite'
Requires-Dist: importlib-metadata ; (python_version < "3.8") and extra == 'lite'
Provides-Extra: testing
Requires-Dist: isort ; extra == 'testing'
Requires-Dist: setuptools ; extra == 'testing'
Requires-Dist: tomli ; extra == 'testing'
Requires-Dist: pytest ; extra == 'testing'
Requires-Dist: pytest-cov ; extra == 'testing'
Requires-Dist: pytest-xdist ; extra == 'testing'
Requires-Dist: pytest-randomly ; extra == 'testing'
Requires-Dist: validate-pyproject <2,>=0.6 ; extra == 'testing'
Provides-Extra: typechecking
Requires-Dist: typing-extensions ; (python_version < "3.8") and extra == 'typechecking'

.. These are examples of badges you might want to add to your README:
   please update the URLs accordingly

    .. image:: https://img.shields.io/conda/vn/conda-forge/ini2toml.svg
        :alt: Conda-Forge
        :target: https://anaconda.org/conda-forge/ini2toml
    .. image:: https://pepy.tech/badge/ini2toml/month
        :alt: Monthly Downloads
        :target: https://pepy.tech/project/ini2toml
    .. image:: https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Twitter
        :alt: Twitter
        :target: https://twitter.com/ini2toml

.. image:: https://api.cirrus-ci.com/github/abravalheri/ini2toml.svg?branch=main
    :alt: Built Status
    :target: https://cirrus-ci.com/github/abravalheri/ini2toml
.. image:: https://readthedocs.org/projects/ini2toml/badge/?version=latest
    :alt: ReadTheDocs
    :target: https://ini2toml.readthedocs.io
.. image:: https://img.shields.io/coveralls/github/abravalheri/ini2toml/main.svg
    :alt: Coveralls
    :target: https://coveralls.io/r/abravalheri/ini2toml
.. image:: https://img.shields.io/pypi/v/ini2toml.svg
    :alt: PyPI-Server
    :target: https://pypi.org/project/ini2toml/
.. image:: https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold
    :alt: Project generated with PyScaffold
    :target: https://pyscaffold.org/

|

========
ini2toml
========


    Automatically translates |ini_cfg|_ files into TOML_

.. important:: This project is **experimental** and under active development
   Issue reports and contributions are very welcome.


Description
===========

The original purpose of this project is to help migrating ``setup.cfg`` files
to `PEP 621`_, but by extension it can also be used to convert any compatible |ini_cfg|_
file to TOML_.

Please notice, the provided |ini_cfg|_ files should follow the same syntax
supported by Python's |ConfigParser|_ library (here referred to as INI syntax)
and more specifically abide by |ConfigUpdater|_ restrictions (e.g., no
interpolation or repeated fields).


Usage
=====

``ini2toml`` comes in two flavours: *"lite"* and *"full"*. The "lite"
flavour will create a TOML document that does not contain any of the comments
from the original |ini_cfg| file. On the other hand, the "full" flavour
will make an extra effort to translate these comments into a TOML-equivalent
(please notice sometimes this translation is not perfect, so it is always good
to check the TOML document afterwards).

To get started, you need to install the package, which can be easily done
using |pipx|_:

.. code-block:: bash

    $ pipx install 'ini2toml[lite]'
    # OR
    $ pipx install 'ini2toml[full]'

Now you can use ``ini2toml`` as a command line tool:

.. code-block:: bash

    # in you terminal
    $ ini2toml --help
    $ ini2toml path/to/ini/or/cfg/file

You can also use ``ini2toml`` in your Python scripts or projects:

.. code-block:: python

    # in your python code
    from ini2toml.api import Translator

    profile_name = "setup.cfg"
    toml_str = Translator().translate(original_contents_str, profile_name)

To do so, don't forget to add it to your `virtual environment`_ or specify it as a
`project dependency`_.

More details about ``ini2toml`` and its Python API can be found in `our docs`_.


.. _pyscaffold-notes:

.. tip::
   If you consider contributing to this project, have a look on our
   `contribution guides`_.

Note
====

This project was initially created in the context of PyScaffold, with the
purpose of helping migrating existing projects to `PEP 621`_-style
configuration when it is made available on ``setuptools``.
For details and usage information on PyScaffold see https://pyscaffold.org/.


.. |ini_cfg| replace:: ``.ini/.cfg``
.. |ConfigParser| replace:: ``ConfigParser``
.. |ConfigUpdater| replace:: ``ConfigUpdater``
.. |pipx| replace:: ``pipx``

.. _ConfigParser: https://docs.python.org/3/library/configparser.html
.. _ConfigUpdater: https://github.com/pyscaffold/configupdater
.. _contribution guides: https://ini2toml.readthedocs.io/en/latest/contributing.html
.. _ini_cfg: https://docs.python.org/3/library/configparser.html#supported-ini-file-structure
.. _our docs: https://ini2toml.readthedocs.io
.. _PEP 621: https://www.python.org/dev/peps/pep-0621/
.. _pipx: https://pypa.github.io/pipx/
.. _project dependency: https://packaging.python.org/tutorials/managing-dependencies/
.. _TOML: https://toml.io/en/
.. _TOML library: https://github.com/sdispater/tomlkit
.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/
