| Name | icecream-truck JSON |
| Version |
1.0a0
JSON |
| download |
| home_page | None |
| Summary | Flexible factory for Icecream debuggers. |
| upload_time | 2025-03-16 21:07:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
debug
icecream
introspect
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. vim: set fileencoding=utf-8:
.. -*- coding: utf-8 -*-
.. +--------------------------------------------------------------------------+
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
+--------------------------------------------------------------------------+
*******************************************************************************
icecream-truck
*******************************************************************************
.. image:: https://img.shields.io/pypi/v/icecream-truck
:alt: Package Version
:target: https://pypi.org/project/icecream-truck/
.. image:: https://img.shields.io/pypi/status/icecream-truck
:alt: PyPI - Status
:target: https://pypi.org/project/icecream-truck/
.. image:: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml/badge.svg?branch=master&event=push
:alt: Tests Status
:target: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml
.. image:: https://emcd.github.io/python-icecream-truck/coverage.svg
:alt: Code Coverage Percentage
:target: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml
.. image:: https://img.shields.io/github/license/emcd/python-icecream-truck
:alt: Project License
:target: https://github.com/emcd/python-icecream-truck/blob/master/LICENSE.txt
.. image:: https://img.shields.io/pypi/pyversions/icecream-truck
:alt: Python Versions
:target: https://pypi.org/project/icecream-truck/
.. image:: https://raw.githubusercontent.com/emcd/python-icecream-truck/master/data/pictures/logo.svg
:alt: Icecream Truck Logo
:width: 800
:align: center
🍦 **Flavorful Debugging** - A Python library which enhances the powerful and
well-known `icecream <https://github.com/gruns/icecream>`_ package with
flavored traces, module hierarchies, and custom outputs. Load up the truck and
roll out delicious debug prints for applications and libraries alike!
Key Features ⭐
===============================================================================
🍒 **Debugger Flavors**: Numeric trace depths to control level of debugging
detail (e.g., ``1``) or custom named flavors for specific subsystems (e.g.,
``io``, ``reporting``), traditional logging levels (e.g., ``info``, ``error``),
or whatever else you can imagine.
🌳 **Module Hierarchy**: Global and per-module configs with inheritance for
precise control over output prefixes, formatters, custom flavors, etc....
🖨️ **Printer Factory**: Dyanamically associate output functions with debugger
objects based on module name, flavor, etc... — swap in customized ``print``,
``logging``, ``rich.console``, or other sinks as desired.
📚 **Library-Friendly**: Non-intrusive registration for libraries without
stepping on application debugger/logging configuration.
🚦 **Disabled by Default**: Can leave in production code and explicitly
activate portions as needed. (Performance and security considerations
notwithstanding.)
Installation 📦
===============================================================================
::
pip install icecream-truck
Examples 💡
===============================================================================
Universal Availability
-------------------------------------------------------------------------------
Install as a Python builtin (default alias, ``ictr``) and then use anywhere in
your codebase:
.. code-block:: python
from ictruck import install
install( trace_levels = 3 ) # Enable TRACE0 to TRACE3
message = "Hello, debug world!"
ictr( 1 )( message ) # Prints: TRACE1| message: 'Hello, debug world!'
Library Registration
-------------------------------------------------------------------------------
Libraries can register their own configurations without overriding those of the
application or other libraries. By default, the name of the calling module is
used to register a configuration:
.. code-block:: python
from ictruck import ModuleConfiguration, register_module
register_module( configuration = ModuleConfiguration( ... ) )
Recipes for Customization
-------------------------------------------------------------------------------
E.g., integrate ``icecream``-based introspection and formatting with the
``logging`` module in the Python standard library:
.. code-block:: python
import logging
from ictruck import produce_logging_truck
logging.basicConfig( level = logging.INFO )
truck = produce_logging_truck( )
admonition = "Careful now!"
answer = 42
truck( 'warning' )( admonition ) # Logs: WARNING:__main__:ic| admonition: 'Careful now!'
truck( 'info' )( answer ) # Logs: INFO:__main__:ic| answer: 42
## Note: Module name will be from whatever module calls the truck.
Motivation 🚚
===============================================================================
Why ``icecream-truck``?
There is nothing wrong with the ``icecream`` or ``logging`` packages. However,
there are times that the author of ``icecream-truck`` has wanted, for various
reasons, more than these packages inherently offer:
* **Coexistence**: Application and libraries can coexist without configuration
clashes.
- Library developers are `strongly advised not to create custom levels
<https://docs.python.org/3/howto/logging.html#custom-levels>`_ in
``logging``.
- Library developers are `advised on how to avoid polluting stderr
<https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library>`_
in ``logging``, when an application has not supplied a configuration.
- Loggers `propagate upwards
<https://docs.python.org/3/library/logging.html#logging.Logger.propagate>`_
by default in ``logging``. This means that libraries must explicitly
opt-out of propagation if their authors want to be good citizens and not
contribute to noise pollution / signal obfuscation.
* **Granularity**: Control of debug output by depth threshold and subsystem.
- Only one default debugging level (``DEBUG``) with ``logging``. Libraries
cannot safely extend this. (See point about coexistence).
- No concept of debugging level with ``ic`` builtin. Need to orchestrate
multiple ``icecream.IceCreamDebugger`` instances to support this. (In fact,
this is what ``icecream-truck`` does.)
- While logger hierarchies in ``logging`` do support the notion of software
subsystems, hierarchies are not always the most convenient or abbreviated
way of representing subsystems which span parts or entireties of modules.
* **Signal**: Prevention of undesirable library chatter.
- The ``logging`` root logger will log all messages, at its current log
level or higher, which propagate up to it. Many Python libraries have
opt-out rather than opt-in logging, so you see all of their ``DEBUG`` and
``INFO`` spam unless you surgically manipulate their loggers or squelch
the overall log level.
- Use of the ``ic`` builtin is only recommended for temporary debugging. It
cannot be left in production code without spamming. While the ``enabled``
flag on the ``ic`` builtin can be set to false, it is easy to forget and
also applies to every place where ``ic`` is used in the code. (See point
about granularity.)
* **Extensibility**: More natural integration with packages like ``rich`` via
robust recipes.
- While it is not difficult to change the ``argToStringFunction`` on ``ic``
to be ``rich.pretty.pretty_repr``, there is some repetitive code involved
in each project which wants to do this. And, from a safety perspective,
there should be a fallback if ``rich`` fails to import.
- Similarly, one can add a ``rich.logging.RichHandler`` instance to a logger
instance with minimal effort. However, depending on the the target output
stream, one may also need to build a ``rich.console.Console`` first and
pass that to the handler. This handler will also compete with whatever
handler has been set on the root logger. So, some care must be taken to
prevent propagation. Again, this is repetitive code across projects and
there are import safety fallbacks to consider.
Contribution 🤝
===============================================================================
Contributions welcome! See the `contribution guide
<https://github.com/emcd/python-icecream-truck/tree/master/documentation/sphinx/contribution>`_
for details.
`More Flair <https://www.imdb.com/title/tt0151804/characters/nm0431918>`_
===============================================================================
.. image:: https://img.shields.io/github/last-commit/emcd/python-icecream-truck
:alt: GitHub last commit
:target: https://github.com/emcd/python-icecream-truck
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json
:alt: Copier
:target: https://github.com/copier-org/copier
.. image:: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
:alt: Hatch
:target: https://github.com/pypa/hatch
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
:alt: pre-commit
:target: https://github.com/pre-commit/pre-commit
.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
:alt: Bandit
:target: https://github.com/PyCQA/bandit
.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
:alt: Pylint
:target: https://github.com/pylint-dev/pylint
.. image:: https://microsoft.github.io/pyright/img/pyright_badge.svg
:alt: Pyright
:target: https://microsoft.github.io/pyright
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:alt: Ruff
:target: https://github.com/astral-sh/ruff
.. image:: https://img.shields.io/badge/hypothesis-tested-brightgreen.svg
:alt: Hypothesis
:target: https://hypothesis.readthedocs.io/en/latest/
.. image:: https://img.shields.io/pypi/implementation/icecream-truck
:alt: PyPI - Implementation
:target: https://pypi.org/project/icecream-truck/
.. image:: https://img.shields.io/pypi/wheel/icecream-truck
:alt: PyPI - Wheel
:target: https://pypi.org/project/icecream-truck/
Raw data
{
"_id": null,
"home_page": null,
"name": "icecream-truck",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "debug, icecream, introspect",
"author": null,
"author_email": "Eric McDonald <emcd@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/6b/09/6cff11820bd9bb47ee582b906d17c27586f76b2264ebec90b6f326ccc91b/icecream_truck-1.0a0.tar.gz",
"platform": null,
"description": ".. vim: set fileencoding=utf-8:\n.. -*- coding: utf-8 -*-\n.. +--------------------------------------------------------------------------+\n | |\n | Licensed under the Apache License, Version 2.0 (the \"License\"); |\n | you may not use this file except in compliance with the License. |\n | You may obtain a copy of the License at |\n | |\n | http://www.apache.org/licenses/LICENSE-2.0 |\n | |\n | Unless required by applicable law or agreed to in writing, software |\n | distributed under the License is distributed on an \"AS IS\" BASIS, |\n | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |\n | See the License for the specific language governing permissions and |\n | limitations under the License. |\n | |\n +--------------------------------------------------------------------------+\n\n*******************************************************************************\n icecream-truck\n*******************************************************************************\n\n.. image:: https://img.shields.io/pypi/v/icecream-truck\n :alt: Package Version\n :target: https://pypi.org/project/icecream-truck/\n\n.. image:: https://img.shields.io/pypi/status/icecream-truck\n :alt: PyPI - Status\n :target: https://pypi.org/project/icecream-truck/\n\n.. image:: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml/badge.svg?branch=master&event=push\n :alt: Tests Status\n :target: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml\n\n.. image:: https://emcd.github.io/python-icecream-truck/coverage.svg\n :alt: Code Coverage Percentage\n :target: https://github.com/emcd/python-icecream-truck/actions/workflows/tester.yaml\n\n.. image:: https://img.shields.io/github/license/emcd/python-icecream-truck\n :alt: Project License\n :target: https://github.com/emcd/python-icecream-truck/blob/master/LICENSE.txt\n\n.. image:: https://img.shields.io/pypi/pyversions/icecream-truck\n :alt: Python Versions\n :target: https://pypi.org/project/icecream-truck/\n\n.. image:: https://raw.githubusercontent.com/emcd/python-icecream-truck/master/data/pictures/logo.svg\n :alt: Icecream Truck Logo\n :width: 800\n :align: center\n\n\n\ud83c\udf66 **Flavorful Debugging** - A Python library which enhances the powerful and\nwell-known `icecream <https://github.com/gruns/icecream>`_ package with\nflavored traces, module hierarchies, and custom outputs. Load up the truck and\nroll out delicious debug prints for applications and libraries alike!\n\nKey Features \u2b50\n===============================================================================\n\n\ud83c\udf52 **Debugger Flavors**: Numeric trace depths to control level of debugging\ndetail (e.g., ``1``) or custom named flavors for specific subsystems (e.g.,\n``io``, ``reporting``), traditional logging levels (e.g., ``info``, ``error``),\nor whatever else you can imagine.\n\n\ud83c\udf33 **Module Hierarchy**: Global and per-module configs with inheritance for\nprecise control over output prefixes, formatters, custom flavors, etc....\n\n\ud83d\udda8\ufe0f **Printer Factory**: Dyanamically associate output functions with debugger\nobjects based on module name, flavor, etc... \u2014 swap in customized ``print``,\n``logging``, ``rich.console``, or other sinks as desired.\n\n\ud83d\udcda **Library-Friendly**: Non-intrusive registration for libraries without\nstepping on application debugger/logging configuration.\n\n\ud83d\udea6 **Disabled by Default**: Can leave in production code and explicitly\nactivate portions as needed. (Performance and security considerations\nnotwithstanding.)\n\nInstallation \ud83d\udce6\n===============================================================================\n\n::\n\n pip install icecream-truck\n\nExamples \ud83d\udca1\n===============================================================================\n\nUniversal Availability\n-------------------------------------------------------------------------------\n\nInstall as a Python builtin (default alias, ``ictr``) and then use anywhere in\nyour codebase:\n\n.. code-block:: python\n\n from ictruck import install\n install( trace_levels = 3 ) # Enable TRACE0 to TRACE3\n message = \"Hello, debug world!\"\n ictr( 1 )( message ) # Prints: TRACE1| message: 'Hello, debug world!'\n\nLibrary Registration\n-------------------------------------------------------------------------------\n\nLibraries can register their own configurations without overriding those of the\napplication or other libraries. By default, the name of the calling module is\nused to register a configuration:\n\n.. code-block:: python\n\n from ictruck import ModuleConfiguration, register_module\n register_module( configuration = ModuleConfiguration( ... ) )\n\nRecipes for Customization\n-------------------------------------------------------------------------------\n\nE.g., integrate ``icecream``-based introspection and formatting with the\n``logging`` module in the Python standard library:\n\n.. code-block:: python\n\n import logging\n from ictruck import produce_logging_truck\n logging.basicConfig( level = logging.INFO )\n truck = produce_logging_truck( )\n admonition = \"Careful now!\"\n answer = 42\n truck( 'warning' )( admonition ) # Logs: WARNING:__main__:ic| admonition: 'Careful now!'\n truck( 'info' )( answer ) # Logs: INFO:__main__:ic| answer: 42\n ## Note: Module name will be from whatever module calls the truck.\n\nMotivation \ud83d\ude9a\n===============================================================================\n\nWhy ``icecream-truck``?\n\nThere is nothing wrong with the ``icecream`` or ``logging`` packages. However,\nthere are times that the author of ``icecream-truck`` has wanted, for various\nreasons, more than these packages inherently offer:\n\n* **Coexistence**: Application and libraries can coexist without configuration\n clashes.\n\n - Library developers are `strongly advised not to create custom levels\n <https://docs.python.org/3/howto/logging.html#custom-levels>`_ in\n ``logging``.\n\n - Library developers are `advised on how to avoid polluting stderr\n <https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library>`_\n in ``logging``, when an application has not supplied a configuration.\n\n - Loggers `propagate upwards\n <https://docs.python.org/3/library/logging.html#logging.Logger.propagate>`_\n by default in ``logging``. This means that libraries must explicitly\n opt-out of propagation if their authors want to be good citizens and not\n contribute to noise pollution / signal obfuscation.\n\n* **Granularity**: Control of debug output by depth threshold and subsystem.\n\n - Only one default debugging level (``DEBUG``) with ``logging``. Libraries\n cannot safely extend this. (See point about coexistence).\n\n - No concept of debugging level with ``ic`` builtin. Need to orchestrate\n multiple ``icecream.IceCreamDebugger`` instances to support this. (In fact,\n this is what ``icecream-truck`` does.)\n\n - While logger hierarchies in ``logging`` do support the notion of software\n subsystems, hierarchies are not always the most convenient or abbreviated\n way of representing subsystems which span parts or entireties of modules.\n\n* **Signal**: Prevention of undesirable library chatter.\n\n - The ``logging`` root logger will log all messages, at its current log\n level or higher, which propagate up to it. Many Python libraries have\n opt-out rather than opt-in logging, so you see all of their ``DEBUG`` and\n ``INFO`` spam unless you surgically manipulate their loggers or squelch\n the overall log level.\n\n - Use of the ``ic`` builtin is only recommended for temporary debugging. It\n cannot be left in production code without spamming. While the ``enabled``\n flag on the ``ic`` builtin can be set to false, it is easy to forget and\n also applies to every place where ``ic`` is used in the code. (See point\n about granularity.)\n\n* **Extensibility**: More natural integration with packages like ``rich`` via\n robust recipes.\n\n - While it is not difficult to change the ``argToStringFunction`` on ``ic``\n to be ``rich.pretty.pretty_repr``, there is some repetitive code involved\n in each project which wants to do this. And, from a safety perspective,\n there should be a fallback if ``rich`` fails to import.\n\n - Similarly, one can add a ``rich.logging.RichHandler`` instance to a logger\n instance with minimal effort. However, depending on the the target output\n stream, one may also need to build a ``rich.console.Console`` first and\n pass that to the handler. This handler will also compete with whatever\n handler has been set on the root logger. So, some care must be taken to\n prevent propagation. Again, this is repetitive code across projects and\n there are import safety fallbacks to consider.\n\nContribution \ud83e\udd1d\n===============================================================================\n\nContributions welcome! See the `contribution guide\n<https://github.com/emcd/python-icecream-truck/tree/master/documentation/sphinx/contribution>`_\nfor details.\n\n`More Flair <https://www.imdb.com/title/tt0151804/characters/nm0431918>`_\n===============================================================================\n\n.. image:: https://img.shields.io/github/last-commit/emcd/python-icecream-truck\n :alt: GitHub last commit\n :target: https://github.com/emcd/python-icecream-truck\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json\n :alt: Copier\n :target: https://github.com/copier-org/copier\n\n.. image:: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg\n :alt: Hatch\n :target: https://github.com/pypa/hatch\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\n :alt: pre-commit\n :target: https://github.com/pre-commit/pre-commit\n\n.. image:: https://img.shields.io/badge/security-bandit-yellow.svg\n :alt: Bandit\n :target: https://github.com/PyCQA/bandit\n\n.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n :alt: Pylint\n :target: https://github.com/pylint-dev/pylint\n\n.. image:: https://microsoft.github.io/pyright/img/pyright_badge.svg\n :alt: Pyright\n :target: https://microsoft.github.io/pyright\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n :alt: Ruff\n :target: https://github.com/astral-sh/ruff\n\n.. image:: https://img.shields.io/badge/hypothesis-tested-brightgreen.svg\n :alt: Hypothesis\n :target: https://hypothesis.readthedocs.io/en/latest/\n\n.. image:: https://img.shields.io/pypi/implementation/icecream-truck\n :alt: PyPI - Implementation\n :target: https://pypi.org/project/icecream-truck/\n\n.. image:: https://img.shields.io/pypi/wheel/icecream-truck\n :alt: PyPI - Wheel\n :target: https://pypi.org/project/icecream-truck/\n",
"bugtrack_url": null,
"license": null,
"summary": "Flexible factory for Icecream debuggers.",
"version": "1.0a0",
"project_urls": {
"Documentation": "https://emcd.github.io/python-icecream-truck",
"Download": "https://pypi.org/project/icecream-truck/#files",
"Homepage": "https://github.com/emcd/python-icecream-truck",
"Issue Tracker": "https://github.com/emcd/python-icecream-truck/issues",
"Source Code": "https://github.com/emcd/python-icecream-truck"
},
"split_keywords": [
"debug",
" icecream",
" introspect"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5a990c70bee876b89714c603b3d96c02dc7a839856cdae01167738e84ee7217",
"md5": "10378dcfb0b85580b89225e68ba56529",
"sha256": "9b7c552742486533a646798403a76cfc9d1b93c84be746fda02cd4482f3c3fd4"
},
"downloads": -1,
"filename": "icecream_truck-1.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10378dcfb0b85580b89225e68ba56529",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20883,
"upload_time": "2025-03-16T21:07:14",
"upload_time_iso_8601": "2025-03-16T21:07:14.971878Z",
"url": "https://files.pythonhosted.org/packages/b5/a9/90c70bee876b89714c603b3d96c02dc7a839856cdae01167738e84ee7217/icecream_truck-1.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6b096cff11820bd9bb47ee582b906d17c27586f76b2264ebec90b6f326ccc91b",
"md5": "ce55f0e8ceacce1d47863818842dd57c",
"sha256": "d0d9a0183f3b34c197467821915df308ad0df5351d0be3c656c8fe2ae0a9db5c"
},
"downloads": -1,
"filename": "icecream_truck-1.0a0.tar.gz",
"has_sig": false,
"md5_digest": "ce55f0e8ceacce1d47863818842dd57c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19267,
"upload_time": "2025-03-16T21:07:16",
"upload_time_iso_8601": "2025-03-16T21:07:16.563203Z",
"url": "https://files.pythonhosted.org/packages/6b/09/6cff11820bd9bb47ee582b906d17c27586f76b2264ebec90b6f326ccc91b/icecream_truck-1.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-16 21:07:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "emcd",
"github_project": "python-icecream-truck",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "icecream-truck"
}
