{"id":20548603,"url":"https://github.com/kenkundert/nestedtext","last_synced_at":"2025-05-15T00:06:45.241Z","repository":{"id":36999454,"uuid":"290086759","full_name":"KenKundert/nestedtext","owner":"KenKundert","description":"Human readable and writable data interchange format","archived":false,"fork":false,"pushed_at":"2025-04-05T19:36:24.000Z","size":793,"stargazers_count":381,"open_issues_count":1,"forks_count":13,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-06T17:04:44.163Z","etag":null,"topics":["config","configuration","configuration-files","data","json","json-alternative","nested-text","nestedtext","serialization","toml","toml-alternative","yaml","yaml-alternative","yaml-configuration"],"latest_commit_sha":null,"homepage":"https://nestedtext.org","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/KenKundert.png","metadata":{"files":{"readme":"README.rst","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-08-25T02:01:04.000Z","updated_at":"2025-04-05T19:36:27.000Z","dependencies_parsed_at":"2024-03-18T00:29:44.834Z","dependency_job_id":"2da47615-4734-4cc6-8f81-cf546f252307","html_url":"https://github.com/KenKundert/nestedtext","commit_stats":{"total_commits":522,"total_committers":8,"mean_commits":65.25,"dds":0.03448275862068961,"last_synced_commit":"9ec7823a8ad0c3cd667a3b89fe2b7152fe591742"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fnestedtext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fnestedtext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fnestedtext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Fnestedtext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KenKundert","download_url":"https://codeload.github.com/KenKundert/nestedtext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248767612,"owners_count":21158497,"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":["config","configuration","configuration-files","data","json","json-alternative","nested-text","nestedtext","serialization","toml","toml-alternative","yaml","yaml-alternative","yaml-configuration"],"created_at":"2024-11-16T02:13:59.357Z","updated_at":"2025-04-13T19:29:40.935Z","avatar_url":"https://github.com/KenKundert.png","language":"Python","readme":"NestedText — A Human Friendly Data Format\n=========================================\n\n|downloads| |build status| |coverage| |rtd status| |pypi version| |anaconda version| |python version|\n\n\n| Authors: Ken \u0026 Kale Kundert\n| Version: 3.8.dev2\n| Released: 2025-04-05\n| Documentation: nestedtext.org_\n| Please post all questions, suggestions, and bug reports to GitHub_.\n|\n\n*NestedText* is a file format for holding structured data.  It is similar in \nconcept to JSON_, except that *NestedText* is designed to make it easy for \npeople to enter, edit, or view the data directly.  It organizes the data into \na nested collection of name-value pairs, lists, and strings.  The syntax is \nintended to be very simple and intuitive for most people.\n\nA unique feature of this file format is that it only supports one scalar type: \nstrings.  As such, quoting strings is unnecessary, and without quoting there is \nno need for escaping.  While the decision to forego other types (integers, \nreals, Booleans, etc.) may seem counter productive, it leads to simpler data \nfiles and applications that are more robust.\n\n*NestedText* is convenient for configuration files, data journals, address \nbooks, account information, and the like.  Here is an example of a file that \ncontains a few addresses:\n\n.. code-block:: nestedtext\n\n    # Contact information for our officers\n\n    Katheryn McDaniel:\n        position: president\n        address:\n            \u003e 138 Almond Street\n            \u003e Topeka, Kansas 20697\n        phone:\n            cell: 1-210-555-5297\n            home: 1-210-555-8470\n                # Katheryn prefers that we always call her on her cell phone.\n        email: KateMcD@aol.com\n        additional roles:\n            - board member\n\n    Margaret Hodge:\n        position: vice president\n        address:\n            \u003e 2586 Marigold Lane\n            \u003e Topeka, Kansas 20682\n        phone: 1-470-555-0398\n        email: margaret.hodge@ku.edu\n        additional roles:\n            - new membership task force\n            - accounting task force\n\nTypical Applications\n--------------------\n\nConfiguration\n\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nConfiguration files are an attractive application for *NestedText*.  \n*NestedText* configuration files tend to be simple, clean and unambiguous.  \nPlus, they handle hierarchy much better than alternatives such as Ini_ and \nTOML_.\n\n\nStructured Code\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nOne way to build tools to tackle difficult and complex tasks is to provide an \napplication specific language.  That can be a daunting challenge.  However, in \ncertain cases, such as specifying complex configurations, *NestedText* can help \nmake the task much easier.  *NestedText* conveys the structure of data leaving \nthe end application to interpret the data itself.  It can do so with \na collection of small parsers that are tailored to the specific piece of data to \nwhich they are applied.  This generally results in a simpler specification since \neach piece of data can be given in its natural format, which might otherwise \nconfuse a shared parser.  In this way, rather than building one large very \ngeneral language and parser, a series of much smaller and simpler parsers are \nneeded.  These smaller parsers can be as simple as splitters or partitioners, \nvalue checkers, or converters for numbers in special forms (numbers with units, \ntimes or dates, GPS coordinates, etc.).  Or they could be full-blown expression \nevaluators or mini-languages.  Structured code provides a nice middle ground \nbetween data and code and its use is growing in popularity.\n\nAn example of structured code is provided by GitHub with its workflow \nspecification files.  They use YAML_.  Unfortunately, the syntax of the code \nsnippets held in the various fields can be confused with *YAML* syntax, which \nleads to unnecessary errors, confusion, and complexity (see *YAML issues*).  \nJSON_ suffers from similar problems.  *NestedText* excels for these applications \nas it holds code snippets without any need for quoting or escaping.  \n*NestedText* provides simple unambiguous rules for defining the structure of \nyour data and when these rules are followed there is no way for any syntax or \nspecial characters in the values of your data to be confused with *NestedText* \nsyntax.  In fact, it is possible for *NestedText* to hold *NestedText* snippets \nwithout conflict.\n\nAnother example of structured code is provided by the files that contain the \ntest cases used by `Parametrize From File`_, a PyTest_ plugin.\n*Parametrize From File* simplifies the task of specifying test cases for \n*PyTest* by separating the test cases from the test code.  Here it is being \napplied to test a command line program.  Its response is checked using regular \nexpressions.  Each entry includes a shell command to run the program and \na regular expression that must match the output for the test to pass::\n\n    -\n        cmd: emborg version\n        expected: emborg version: \\d+\\.\\d+(\\.\\d+(\\.?\\w+\\d+)?)?  \\(\\d\\d\\d\\d-\\d\\d-\\d\\d\\)\n        expected type: regex\n    -\n        cmd: emborg --quiet files -D\n        expected:\n            \u003e Archive: home-\\d\\d\\d\\d-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d\n            \u003e \\d\\d\\d\\d-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d.\\d\\d\\d\\d\\d\\d configs/subdir/(file|)\n            \u003e \\d\\d\\d\\d-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d.\\d\\d\\d\\d\\d\\d configs/subdir/(file|)\n                # Unfortunately, we cannot check the order as they were both \n                # created at the same time.\n        expected type: regex\n    -\n        cmd: emborg due --backup-days 1 --message \"{elapsed} since last {action}\"\n        expected: home: (\\d+(\\.\\d)? (seconds|minutes)) since last backup\\.\n        expected type: regex\n\nNotice that the regular expressions are given clean, without any quoting or \nescaping.\n\n\nComposable Utilities\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nAnother attractive use-case for *NestedText* is command line programs whose \noutput is meant to be consumed by either people or other programs.  This is \nanother growing trend.  Many programs do this by supporting a ``--json`` \ncommand-line flag that indicates the output should be computer readable rather \nthan human readable.  But, with *NestedText* it is not necessary to make people \nchoose.  Just output the result in *NestedText* and it can be read by people or \ncomputers.  For example, consider a program that reads your address list and \noutput particular fields on demand::\n\n    \u003e address --email\n    Katheryn McDaniel: KateMcD@aol.com\n    Margaret Hodge: margaret.hodge@ku.edu\n\nThis output could be fed directly into another program that accepts *NestedText* \nas input::\n\n    \u003e address --email | mail-to-list\n\n\nContributing\n------------\n\nThis package contains a Python reference implementation of *NestedText* and \na test suite.  Implementation in many languages is required for *NestedText* to \ncatch on widely.  If you like the format, please consider contributing \nadditional implementations.\n\nAlso, please consider using *NestedText* for any applications you create.\n\n\n.. _json: https://www.json.org/json-en.html\n.. _yaml: https://yaml.org/\n.. _toml: https://toml.io/en/\n.. _ini: https://en.wikipedia.org/wiki/INI_file\n.. _parametrize from file: https://parametrize-from-file.readthedocs.io\n.. _pytest: https://docs.pytest.org\n.. _github: https://github.com/KenKundert/nestedtext/issues\n.. _nestedtext.org: https://nestedtext.org\n\n.. |downloads| image:: https://pepy.tech/badge/nestedtext/month\n    :target: https://pepy.tech/project/nestedtext\n\n.. |rtd status| image:: https://img.shields.io/readthedocs/nestedtext.svg\n   :target: https://nestedtext.readthedocs.io/en/latest/?badge=latest\n\n.. |build status| image:: https://github.com/KenKundert/nestedtext/actions/workflows/build.yaml/badge.svg\n    :target: https://github.com/KenKundert/nestedtext/actions/workflows/build.yaml\n\n.. |coverage| image:: https://coveralls.io/repos/github/KenKundert/nestedtext/badge.svg?branch=master\n    :target: https://coveralls.io/github/KenKundert/nestedtext?branch=master\n\n.. |pypi version| image:: https://img.shields.io/pypi/v/nestedtext.svg\n    :target: https://pypi.python.org/pypi/nestedtext\n\n.. |anaconda version| image:: https://anaconda.org/conda-forge/nestedtext/badges/version.svg\n    :target: https://anaconda.org/conda-forge/nestedtext\n\n.. |python version| image:: https://img.shields.io/pypi/pyversions/nestedtext.svg\n    :target: https://pypi.python.org/pypi/nestedtext\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Fnestedtext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenkundert%2Fnestedtext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Fnestedtext/lists"}