{"id":20548649,"url":"https://github.com/kenkundert/inform","last_synced_at":"2025-04-14T10:53:20.697Z","repository":{"id":52380445,"uuid":"46948811","full_name":"KenKundert/inform","owner":"KenKundert","description":"Library of print utilities used when outputting messages for the user from command-line programs.","archived":false,"fork":false,"pushed_at":"2024-08-05T19:03:21.000Z","size":681,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-29T23:18:35.637Z","etag":null,"topics":["debug","error-handling","error-reporting","logger","logging","print","printing"],"latest_commit_sha":null,"homepage":"https://inform.readthedocs.io","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":"2015-11-26T22:12:56.000Z","updated_at":"2024-08-05T19:03:25.000Z","dependencies_parsed_at":"2024-04-27T20:33:08.480Z","dependency_job_id":"facf528d-9f9d-4c9a-b9a5-90b0376cb24b","html_url":"https://github.com/KenKundert/inform","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Finform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Finform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Finform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KenKundert%2Finform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KenKundert","download_url":"https://codeload.github.com/KenKundert/inform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868774,"owners_count":21174756,"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":["debug","error-handling","error-reporting","logger","logging","print","printing"],"created_at":"2024-11-16T02:14:08.781Z","updated_at":"2025-04-14T10:53:20.690Z","avatar_url":"https://github.com/KenKundert.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Inform — Print \u0026 Logging Utilities\n==================================\n\n|downloads| |build status| |coverage| |rtd status| |pypi version| |anaconda version| |python version|\n\n:Author: Ken Kundert\n:Version: 1.33\n:Released: 2024-12-11\n\nA package that provides specialized print functions that are used when \ncommunicating with the user. It allows you to easily print attractive, \ninformative, and consistent error messages.  For example:\n\n.. code-block:: python\n\n    \u003e\u003e from inform import display, warn, error\n    \u003e\u003e display(\n    ..     'Display is like print'\n    ..     'except that it supports logging and can be disabled.'\n    ..     sep=', ')\n    Display is like print, except that it supports logging and can be disabled.\n\n    \u003e\u003e warn('warnings get a header that is printed in yellow.')\n    warning: warnings get a header that is printed in yellow.\n\n    \u003e\u003e error('errors get a header that is printed in red.')\n    error: errors get a header that is printed in red.\n\nInform also provides logging and output control.\n\nIn addition, Inform provides a powerful generic exception that can be used \ndirectly as a general purpose exception, or can be subclassed to produce \npowerful specialized exceptions.  Inform exceptions are unique in that they keep \nall of the named and unnamed arguments so they can be used when reporting \nerrors.\n\nYou can find the documentation on `ReadTheDocs\n\u003chttps://inform.readthedocs.io\u003e`_. You can download and install the latest\nstable version of the code from `PyPI \u003chttps://pypi.python.org\u003e`_ using::\n\n    pip3 install inform\n\nYou can find the latest development version of the source code on\n`Github \u003chttps://github.com/KenKundert/inform\u003e`_.\n\n\nIntroduction\n------------\n\nThis package defines a collection of *print* functions that have different \nroles.  These functions are referred to as *informants* and are described below \nin the Informants section. They include include *log*, *comment*, *codicil*, \n*narrate*, *display*, *output*, *notify*, *debug*, *warn*, *error*, *fatal* and \n*panic*.\n\nWith the simplest use of the program, you simply import the informants you need \nand call them (they take the same arguments as Python's built-in *print* \nfunction):\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import display\n    \u003e\u003e\u003e display('ice', 9)\n    ice 9\n\nFor more control of the informants, you can import and instantiate the Inform \nclass yourself along with the desired informants.  This gives you the ability to \nspecify options:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import Inform, display, error\n    \u003e\u003e\u003e Inform(logfile=False, prog_name=False)\n    \u003c...\u003e\n    \u003e\u003e\u003e display('hello')\n    hello\n    \u003e\u003e\u003e error('file not found.', culprit='data.in')\n    error: data.in: file not found.\n\nAn object of the Inform class is referred to as an informer (not to be confused \nwith the print functions, which are  referred to as informants). Once \ninstantiated, you can use the informer to change various settings, terminate the \nprogram, or return a count of the number of errors that have occurred.\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import Inform, error\n    \u003e\u003e\u003e informer = Inform(prog_name=\"prog\")\n    \u003e\u003e\u003e error('file not found.', culprit='data.in')\n    prog error: data.in: file not found.\n    \u003e\u003e\u003e informer.errors_accrued()\n    1\n\nYou can create your own informants:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import Inform, InformantFactory\n\n    \u003e\u003e\u003e verbose1 = InformantFactory(output=lambda m: m.verbosity \u003e= 1)\n    \u003e\u003e\u003e verbose2 = InformantFactory(output=lambda m: m.verbosity \u003e= 2)\n    \u003e\u003e\u003e with Inform(verbosity=0):\n    ...     verbose1('First level of verbosity.')\n    ...     verbose2('Second level of verbosity.')\n\n    \u003e\u003e\u003e with Inform(verbosity=1):\n    ...     verbose1('First level of verbosity.')\n    ...     verbose2('Second level of verbosity.')\n    First level of verbosity.\n\n    \u003e\u003e\u003e with Inform(verbosity=2):\n    ...     verbose1('First level of verbosity.')\n    ...     verbose2('Second level of verbosity.')\n    First level of verbosity.\n    Second level of verbosity.\n\nThe argument *verbosity* is not an explicitly supported argument to Inform.  In \nthis case Inform simply saves the value and makes it available as an attribute, \nand it is this attribute that is queried by the lambda function passed to the \nInformantFactory when creating the informants.\n\n\nException\n---------\nAn exception, *Error*, is provided that takes the same arguments as an \ninformant.  This allows you to catch the exception and handle it if you like.  \nThe exception provides the *report* and *terminate* methods that processes the \nexception as an error or fatal error if you find that you can do nothing else \nwith the exception:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import Inform, Error\n\n    \u003e\u003e\u003e Inform(prog_name='myprog')\n    \u003c...\u003e\n    \u003e\u003e\u003e try:\n    ...     raise Error('must not be zero.', culprit='naught')\n    ... except Error as e:\n    ...     e.report()\n    myprog error: naught: must not be zero.\n\n*Error* also provides get_message() and get_culprit() methods, which return the \nmessage and the culprit. You can also cast the exception to a string to get \na string that contains both the message and the culprit formatted so that it can \nbe shown to the user.\n\nAny keyword arguments provided will be available in *e.kwargs*, but certain \nkeyword arguments are reserved by inform (see above).\n\nOne common approach to using *Error* is to pass all the arguments that make up \nthe error message as unnamed arguments and then assemble them into the message \nby providing a template.  In that way the arguments are directly available to \nthe handler if needed. For example:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from inform import Error, did_you_mean\n\n    \u003e\u003e\u003e known_names = 'alpha beta gamma delta epsilon'.split()\n    \u003e\u003e\u003e name = 'alfa'\n\n    \u003e\u003e\u003e try:\n    ...     if name not in known_names:\n    ...         raise Error(name, template=\"name '{}' is not defined.\")\n    ... except Error as e:\n    ...     candidates = did_you_mean(e.args[0], known_names)\n    ...     e.report(codicil = f\"Did you mean {candidates}?\")\n    myprog error: name 'alfa' is not defined.\n        Did you mean alpha?\n\n\nUtilities\n---------\n\nSeveral utility functions and classes are provided for your convenience. They \nare often helpful when creating messages.\n\ndedent:\n    Dedents a block of text.\n\nindent:\n    Indents a block of text.\n\nconjoin:\n    Like ''.join(), but allows you to specify a conjunction that is placed \n    between the last two elements, ex:\n\n    .. code-block:: python\n\n        \u003e\u003e\u003e from inform import conjoin\n        \u003e\u003e\u003e conjoin(['a', 'b', 'c'])\n        'a, b and c'\n\n        \u003e\u003e\u003e conjoin(['a', 'b', 'c'], conj=' or ')\n        'a, b or c'\n\ndid_you_mean:\n    Given a word and list of candidates, returns the candidate that is most \n    similar to the word.\n\ncull:\n    Strips items from a collection that have a particular value.\n\njoin:\n    Combines the arguments in a manner very similar to an informant and returns \n    the result as a string.\n\nfmt:\n    Similar to ''.format(), but it can pull arguments from the local scope.\n\nrender:\n    Recursively convert an object to a string with reasonable formatting.  Has \n    built in support for the base Python types (None, bool, int, float, str, \n    set, tuple, list, and dict).  If you confine yourself to these types, the \n    output of render() can be read by the Python interpreter. Other types are \n    converted to string with repr().\n\nplural:\n    Produces either the singular or plural form of a word based on a count.\n\ntruth:\n    Like plural, but for Booleans.\n\nfull_stop:\n    Adds a period to the end of the string if needed (if the last character is \n    not a period, question mark or exclamation mark).\n\ntitle_case:\n    Converts the initial letters in the words of a string to upper case while \n    maintaining any letters that are already upper case, such as acronyms.\n\nformat_range, parse_range:\n    Converts a set of numbers to and from a succinct, readable string that \n    summarizes the set.  For example:\n\n    .. code-block:: python\n\n        \u003e\u003e\u003e from inform import format_range, parse_range\n\n        \u003e\u003e\u003e format_range({1, 2, 3, 5})\n        '1-3,5'\n\n        \u003e\u003e\u003e parse_range('1-3,5')\n        {1, 2, 3, 5}\n\ncolumns:\n    Distribute array over enough columns to fill the screen.\n\nos_error:\n    Generates clean messages for operating system errors.\n\nis_str:\n    Returns *True* if its argument is a string-like object.\n\nis_iterable:\n    Returns *True* if its argument is iterable.\n\nis_collection:\n    Returns *True* if its argument is iterable but is not a string.\n\nis_mapping:\n    Returns *True* if its argument is a mapping (are dictionary like).\n\nColor:\n    A class is used to add color to text.\n\nInfo:\n    A utility class that automatically converts all keyword arguments into \n    attributes.\n\nProgessBar:\n    A class that produces an interruptable progress bar.\n\nrender_bar:\n    Converts generates a text bar whose width is controlled by a normalized \n    value.\n\n\n.. |build status| image:: https://github.com/KenKundert/inform/actions/workflows/build.yaml/badge.svg\n    :target: https://github.com/KenKundert/inform/actions/workflows/build.yaml\n\n.. |downloads| image:: https://pepy.tech/badge/inform/month\n    :target: https://pepy.tech/project/inform\n\n.. |rtd status| image:: https://img.shields.io/readthedocs/inform.svg\n   :target: https://inform.readthedocs.io/en/latest/?badge=latest\n\n.. |coverage| image:: https://img.shields.io/coveralls/KenKundert/inform.svg\n    :target: https://coveralls.io/r/KenKundert/inform\n\n.. |pypi version| image:: https://img.shields.io/pypi/v/inform.svg\n    :target: https://pypi.python.org/pypi/inform\n\n.. |anaconda version| image:: https://anaconda.org/conda-forge/inform/badges/version.svg\n    :target: https://anaconda.org/conda-forge/inform\n\n.. |python version| image:: https://img.shields.io/pypi/pyversions/inform.svg\n    :target: https://pypi.python.org/pypi/inform/\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Finform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenkundert%2Finform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenkundert%2Finform/lists"}