{"id":16540264,"url":"https://github.com/pappasam/toml-sort","last_synced_at":"2025-05-15T23:08:20.521Z","repository":{"id":35049150,"uuid":"200658112","full_name":"pappasam/toml-sort","owner":"pappasam","description":"Toml sorting library","archived":false,"fork":false,"pushed_at":"2024-11-19T14:02:41.000Z","size":471,"stargazers_count":105,"open_issues_count":20,"forks_count":21,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-11T10:04:57.433Z","etag":null,"topics":["cli","command-line-parser","command-line-tool","formatter","python-library","python3","sorting","toml","toml-sort"],"latest_commit_sha":null,"homepage":"https://toml-sort.readthedocs.io/en/latest/","language":"Python","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/pappasam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-08-05T13:12:29.000Z","updated_at":"2025-05-06T22:11:10.000Z","dependencies_parsed_at":"2024-06-18T18:12:08.840Z","dependency_job_id":"6ffafd4c-4ca0-476e-a698-a34bd744446a","html_url":"https://github.com/pappasam/toml-sort","commit_stats":{"total_commits":156,"total_committers":12,"mean_commits":13.0,"dds":"0.28205128205128205","last_synced_commit":"2af9ed41cd9fcbbc3bb76d5982bef91a214f773f"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pappasam%2Ftoml-sort","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pappasam%2Ftoml-sort/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pappasam%2Ftoml-sort/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pappasam%2Ftoml-sort/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pappasam","download_url":"https://codeload.github.com/pappasam/toml-sort/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436949,"owners_count":22070947,"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":["cli","command-line-parser","command-line-tool","formatter","python-library","python3","sorting","toml","toml-sort"],"created_at":"2024-10-11T18:51:59.427Z","updated_at":"2025-05-15T23:08:14.289Z","avatar_url":"https://github.com/pappasam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# toml-sort\n\n[![pypi-version](https://img.shields.io/pypi/v/toml-sort.svg)](https://python.org/pypi/toml-sort)\n[![license](https://img.shields.io/pypi/l/toml-sort.svg)](https://python.org/pypi/toml-sort)\n[![image-python-versions](https://img.shields.io/badge/python-\u003e=3.9-blue)](https://python.org/pypi/jedi-language-server)\n[![image-pypi-downloads](https://pepy.tech/badge/toml-sort)](https://pepy.tech/project/toml-sort)\n\nA command line utility to sort and format [toml](https://toml.io/en/) files.\n\n## Installation\n\n```bash\npip install toml-sort\n```\n\n## Motivation\n\nThis library sorts TOML files, providing the following features:\n\n- Sort tables and Arrays of Tables (AoT)\n- Option to sort non-tables / non-AoT's, or not\n- Preserve comments, where possible\n- Standardize whitespace and indentation\n\nI wrote this library/application because I couldn't find any \"good\" sorting utilities for TOML files. Now, I use this as part of my daily workflow. Hopefully it helps you too!\n\n## Command line usage\n\nThis project can be used as either a command line utility or a Python library. Read the docs for an overview of its library capabilities. For command line usage, see below:\n\n```console\n$ toml-sort --help\nusage: toml-sort [-h] [--version] [-o OUTPUT] [-i] [-I] [-a] [--no-sort-tables] [--sort-table-keys]\n                 [--sort-inline-tables] [--sort-inline-arrays] [--sort-first KEYS] [--no-header] [--no-comments]\n                 [--no-header-comments] [--no-footer-comments] [--no-inline-comments] [--no-block-comments]\n                 [--spaces-before-inline-comment {1,2,3,4}] [--spaces-indent-inline-array {2,4,6,8}]\n                 [--trailing-comma-inline-array] [--check]\n                 [F ...]\n\nToml sort: a sorting utility for toml files.\n\npositional arguments:\n  F                     filename(s) to be processed by toml-sort (default: -)\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --version             display version information and exit\n  -o OUTPUT, --output OUTPUT\n                        output filepath (default: '-')\n  -i, --in-place        overwrite the original input file with changes\n  --check               silently check if an original file would be changed by the formatter\n\nsort:\n  change sorting behavior\n\n  -I, --ignore-case     ignore case when sorting\n  -a, --all             sort ALL keys. This implies sort table-keys, inline-tables and inline arrays. (default: only\n                        sort non-inline 'tables and arrays of tables')\n  --no-sort-tables      Disables the default behavior of sorting tables and arrays of tables by their header value.\n                        Setting this option will keep the order of tables in the toml file the same.\n  --sort-table-keys     Sort the keys in tables and arrays of tables (excluding inline tables and arrays).\n  --sort-inline-tables  Sort inline tables.\n  --sort-inline-arrays  Sort inline arrays.\n  --sort-first KEYS     Table keys that will be sorted first in the output. Multiple keys can be given separated by a\n                        comma.\n\ncomments:\n  exclude comments from output\n\n  --no-header           Deprecated. See --no-header-comments\n  --no-comments         remove all comments. Implies no header, footer, inline, or block comments\n  --no-header-comments  remove a document's leading comments\n  --no-footer-comments  remove a document's trailing comments\n  --no-inline-comments  remove a document's inline comments\n  --no-block-comments   remove a document's block comments\n\nformatting:\n  options to change output formatting\n\n  --spaces-before-inline-comment {1,2,3,4}\n                        the number of spaces before an inline comment (default: 1)\n  --spaces-indent-inline-array {2,4,6,8}\n                        the number of spaces to indent a multiline inline array (default: 2)\n  --trailing-comma-inline-array\n                        add trailing comma to the last item in a multiline inline array\n\nExamples:\n\n  - **Stdin -\u003e Stdout**: cat input.toml | toml-sort\n  - **Disk -\u003e Disk**: toml-sort -o output.toml input.toml\n  - **Linting**: toml-sort --check input.toml input2.toml input3.toml\n  - **Inplace Disk**: toml-sort --in-place input.toml input2.toml\n\nReturn codes:\n\n  - 0 : success.\n  - 1 : errors were found\n\nNotes:\n\n  - You cannot redirect from a file to itself in Bash. POSIX shells process\n    redirections first, then execute commands. --in-place exists for this\n    reason\n```\n\n## Configuration file\n\ntoml-sort can also be configured by using the `pyproject.toml` file. If the file exists and has a `tool.tomlsort` section, the configuration is used. If both command line arguments and the configuration are used, the options are merged. In the case of conflicts, the command line option is used.\n\nIn short, the names are the same as on the command line (and have the same meaning), but `-` is replaced with `_`. Please note, that only the below options are supported:\n\n```toml\n[tool.tomlsort]\nall = true\nin_place = true\nno_comments = true\nno_header_comments = true\nno_footer_comments = true\nno_inline_comments = true\nno_block_comments = true\nno_sort_tables = true\nsort_first = [\"key1\", \"key2\"]\nsort_table_keys = true\nsort_inline_tables = true\nsort_inline_arrays = true\nspaces_before_inline_comment = 2\nspaces_indent_inline_array = 4\ntrailing_comma_inline_array = true\ncheck = true\nignore_case = true\n```\n\n### Configuration Overrides\n\nThe `pyproject.toml` configuration file also supports configuration overrides, which are not available as command-line arguments. These overrides allow for fine-grained control of sort options for particular keys.\n\nOnly the following options can be included in an override:\n\n```toml\n[tool.tomlsort.overrides.\"path.to.key\"]\nfirst = [\"key1\", \"key2\"]\ntable_keys = true\ninline_tables = true\ninline_arrays = true\n```\n\nIn the example configuration, `path.to.key` is the key to match. Keys are matched using the [Python fnmatch function](https://docs.python.org/3/library/fnmatch.html), so glob-style wildcards are supported.\n\nFor instance, to disable sorting the table in the following TOML file:\n\n```toml\n[servers.beta]\nip = \"10.0.0.2\"\ndc = \"eqdc10\"\ncountry = \"中国\"\n```\n\nYou can use any of the following overrides:\n\n```toml\n# Overrides in own table\n[tool.tomlsort.overrides.\"servers.beta\"]\ntable_keys = false\n\n# Overrides in the tomlsort table\n[tool.tomlsort]\noverrides.\"servers.beta\".table_keys = false\n\n# Override using a wildcard if config should be applied to all servers keys\n[tool.tomlsort]\noverrides.\"servers.*\".table_keys = false\n```\n\n## Comments\n\nDue to the free form nature of comments, it is hard to include them in a sort in a generic way that will work for everyone. `toml-sort` deals with four different types of comments. They are all enabled by default, but can be disabled using CLI switches, in which case comments of that type will be removed from the output.\n\n### Header\n\nThe first comments in a document, that are followed by a blank line, are treated as a header, and will always remain at the top of the document. If there is no blank line, the comment will be treated as a block comment instead.\n\n```toml\n# This is a header\n# it can be multiple lines, as long as it is followed with a blank line\n# it will always stay at the top of the sorted document\n\ntitle = \"The example\"\n```\n\n### Footer\n\nAny comments at the end of the document, after the last item in the toml, will be treated as a footer, and will always remain at the bottom of the document.\n\n```toml\ntitle = \"The example\"\n\n# this is a footer comment\n```\n\n### Inline\n\nInline comments are comments that are at the end of a line where the start of the line is a toml item.\n\n```toml\ntitle = \"The example\" # This is a inline comment\n```\n\n### Block\n\nBlock comments, are any comments that are on their own line. These comments are treated as _attached_ to the item in the toml that is directly below them, not separated by whitespace. These comments can be multiple lines. Inline comments will appear in the sorted output above the item they were attached to in the input toml.\n\n```toml\n# Comment attached to title\ntitle = \"The example\"\n\n# This comment is an orphan because it\n# is separated from a-section by whitespace\n\n# This comment is attached to a-section\n# attached comments can be multiple lines\n[a-section]\n# This comment is attached to date\ndate = \"2019\"\n```\n\n### Orphan\n\nOrphan comments are any comments that don't fall into the above categories, they will be removed from the output document.\n\n```toml\n# Header comment\n\n# Orphan comment, not attached to any item\n# because there is whitespace before title\n\ntitle = \"The example\"\n\n# This comment is an orphan because it\n# is separated from a-section by whitespace\n\n# This comment is attached to a-section\n[a-section]\n```\n\n## Example\n\nThe following example shows the input, and output, from the CLI with default options.\n\n### Unformatted, unsorted input\n\n```toml\n# My great TOML example\n\n  title = \"The example\"\n\n[[a-section.hello]]\nports = [ 8001, 8001, 8002 ]\ndob = 1979-05-27T07:32:00Z # First class dates? Why not?\n\n\n     # Attached to b-section\n  [b-section]\n  date = \"2018\"\n  name = \"Richard Stallman\"\n\n[[a-section.hello]]\nports = [ 80 ]\n    #Attached to dob\ndob = 1920-05-27T07:32:00Z # Another date!\n\n                          [a-section]\n                          date = \"2019\"\n                          name = \"Samuel Roeca\"\n```\n\n### Formatted, sorted output\n\n```toml\n# My great TOML example\n\ntitle = \"The example\"\n\n[a-section]\ndate = \"2019\"\nname = \"Samuel Roeca\"\n\n[[a-section.hello]]\nports = [ 8001, 8001, 8002 ]\ndob = 1979-05-27T07:32:00Z # First class dates? Why not?\n\n[[a-section.hello]]\nports = [ 80 ]\n# Attached to dob\ndob = 1920-05-27T07:32:00Z # Another date!\n\n# Attached to b-section\n[b-section]\ndate = \"2018\"\nname = \"Richard Stallman\"\n```\n\n## Local Development\n\nLocal development for this project is quite simple.\n\n**Dependencies**\n\nInstall the following tools manually.\n\n- [Poetry\u003e=1.0](https://github.com/sdispater/poetry#installation)\n- [GNU Make](https://www.gnu.org/software/make/)\n\n```bash\nmake setup # set up dev environment\nmake tests # run tests\n```\n\n## Written by\n\nSamuel Roeca, *samuel.roeca@gmail.com*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpappasam%2Ftoml-sort","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpappasam%2Ftoml-sort","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpappasam%2Ftoml-sort/lists"}