Skip to content

Latest commit

 

History

History
212 lines (159 loc) · 8.49 KB

README.rst

File metadata and controls

212 lines (159 loc) · 8.49 KB
Raw
Built Status ReadTheDocs Coveralls PyPI-Server Project generated with PyScaffold

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:

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

Now you can use ini2toml as a command line tool:

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

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

# 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.

Note that the class Translator will try to guess which flavour to use based on the available installed dependencies. If you need something more deterministic, consider using LiteTranslator and FullTranslator, or explicitly specifying the ini_loads_fn and toml_dumps_fn keyword arguments in the constructor.

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

Limitations

ini2toml will try its best to create good quality translations from .ini/.cfg into .toml files. However the tool comes with a set of well known limitations:

  • Although ini2toml attempts to keep the same order/sequence as the original information was written, sometimes that is not compatible with the TOML syntax, and things end up moving around a bit.
  • ini2toml uses ConfigParser + tomli-w for implementing the "lite" flavour and ConfigUpdater + tomlkit for implementing the "full" flavour. Therefore it inherits the limitations from those libraries (please check their documentation for more information). For example:
    • ConfigUpdater, will have trouble to parse interpolations and the related escaping sequence (%%) (in this respect, it behaves more similarly to RawConfigParser than ConfigParser).
    • tomli-w is not very flexible regarding formatting and will have trouble with multi-line strings.
  • ini2toml expects the input to be valid and will not perform extensive checks on the provided document. If something in the output is not working as you would expect, it might be a good idea to check the input.
  • .ini/.cfg files are used in a plethora of use cases and it is impossible to cover all of them in a single code base. Even when considering setup.cfg, there are many packages that define different sections in the document in addition to the basic definition by setuptools. Because of that ini2toml, adopts a "best-effort" approach, that might not correspond to what you expect. If that is the case please consider contributing or creating your own plugin.
  • The translation procedure analyse only the given input. If the original .ini/.cfg file contains references to other files, or behaves differently depending on the existence/presence of other files and directories, the translation will not take that into consideration.

Therefore it is recommended to double check the output and fix any problems before using the .toml files in production.

Can ini2toml also translate setup.py into pyproject.toml?

Working with .py files is not in the scope of the ini2toml project, and therefore this feature is not implemented.

However, you can probably find some tools on PyPI to translate from setup.py into setup.cfg, like setup-py-upgrade and setuptools-py2cfg [1].

Once you have setup.cfg, you can use ini2toml [2].

[1]Such tools are neither maintained by this project, nor tested for integration by ini2toml. It is best to try some of them out and find the one that works for you. Manual corrections might be needed.
[2]Please note that setup.py is a very dynamic format and that not everything can be represented in setup.cfg or pyproject.toml. Indeed, the setuptools' docs explicitly say that setup.py can be used in tandem with pyproject.toml: ideally all the declarative metadata goes to pyproject.toml, but you can keep the dynamic bits in setup.py. Remember: setup.py is a perfectly valid and non deprecated configuration file; what is deprecated is running it as a CLI tool, i.e. python setup.py ....

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/.