{"id":21466729,"url":"https://github.com/edinburgh-genome-foundry/proglog","last_synced_at":"2025-04-05T13:09:44.351Z","repository":{"id":50280393,"uuid":"100142030","full_name":"Edinburgh-Genome-Foundry/Proglog","owner":"Edinburgh-Genome-Foundry","description":":memo: Logs and progress bars manager for Python","archived":false,"fork":false,"pushed_at":"2022-05-05T15:32:47.000Z","size":480,"stargazers_count":114,"open_issues_count":2,"forks_count":5,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-29T12:07:25.427Z","etag":null,"topics":["logger","progress-bar","python"],"latest_commit_sha":null,"homepage":"","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/Edinburgh-Genome-Foundry.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}},"created_at":"2017-08-12T23:04:57.000Z","updated_at":"2025-03-04T00:40:50.000Z","dependencies_parsed_at":"2022-09-24T10:23:22.791Z","dependency_job_id":null,"html_url":"https://github.com/Edinburgh-Genome-Foundry/Proglog","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2FProglog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2FProglog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2FProglog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2FProglog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edinburgh-Genome-Foundry","download_url":"https://codeload.github.com/Edinburgh-Genome-Foundry/Proglog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"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":["logger","progress-bar","python"],"created_at":"2024-11-23T08:15:04.552Z","updated_at":"2025-04-05T13:09:44.238Z","avatar_url":"https://github.com/Edinburgh-Genome-Foundry.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Proglog Logo\" title=\"Proglog Logo\" src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/logo.png\" width=\"500\"\u003e\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003c/p\u003e\n\n.. image:: https://github.com/Edinburgh-Genome-Foundry/Proglog/actions/workflows/build.yml/badge.svg\n    :target: https://github.com/Edinburgh-Genome-Foundry/Proglog/actions/workflows/build.yml\n    :alt: GitHub CI build status\n\n.. image:: https://coveralls.io/repos/github/Edinburgh-Genome-Foundry/Proglog/badge.svg?branch=master\n    :target: https://coveralls.io/github/Edinburgh-Genome-Foundry/Proglog?branch=master\n\nProglog is a progress logging system for Python. It allows to build complex\nlibraries while giving your  users control over logs, callbacks and progress bars.\n\n**What problems does it solve ?**\n\nLibraries like `tqdm \u003chttps://github.com/noamraph/tqdm\u003e`_ or `progress \u003chttps://github.com/verigak/progress/\u003e`_ are great for quickly adding progress bars to your scripts, but become difficult to manage when building larger projects.\n\nFor instance, you will need to write different code depending on whether you are displaying the progress in a console, a Jupyter notebook, or a webpage.\n\nSometimes a single program may have to handle many logs and progress bars coming from different subprograms and libraries, at which case you may want to let the final user decide which progress bars they want to display or to mute, even when these progress bars are handled deep down in your program.\n\nFor instance if your program 1 calls a program 2 and program 3 (possibly from other libraries), you may want to be able to silence the progress bars of routine 2, or to only show the progress bars of routine 1. As long as all routines use Proglog, this will be easy to do.\n\n.. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/run_and_get_progress.png\"    width=\"650\"\u003e\n    \u003c/p\u003e\n\n\nYou may also want to log more than just progress bars, have specific callback fonctions, print the logs in human-readable format... Proglog provides all these features.\n\n\nUsage\n-----\n\nAssume that you are writing a library called ``my_library`` in which you define a routine as follows:\n\n.. code:: python\n\n    import time  # for simulating computing time\n    from proglog import default_bar_logger\n\n    def my_routine(iterations=10, logger='bar'):\n        \"\"\"Run several loops to showcase Proglog.\"\"\"\n        logger = default_bar_logger(logger)  # shorthand to generate a bar logger\n        for i in logger.iter_bar(iteration=range(iterations)):\n            for j in logger.iter_bar(animal=['dog', 'cat', 'rat', 'duck']):\n                time.sleep(0.1)  # simulate some computing time\n\nNow when the library users run a program in the console, they will get a console progress bar:\n\n.. code:: python\n\n    from my_library import my_routine\n    my_routine()\n\n.. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/console_bar.png\"    width=\"450\"\u003e\n    \u003c/p\u003e\n\nIf the users run the routine inside a Jupyter/IPython notebook, they only need to write ``proglog.notebook()`` at the beginning of the notebook to obtain HTML progress bars:\n\n.. code:: python\n\n    import proglog\n    proglog.notebook()\n\n    from my_library import my_routine\n    my_routine()\n\n.. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/notebook_bar.png\"    width=\"450\"\u003e\n    \u003c/p\u003e\n\n\nIf the user wishes to turn off all progress bars:\n\n.. code:: python\n\n    from my_library import my_routine\n    my_routine(logger=None)\n\nIf the user is running the routine on a web server and would want to attach the\ndata to an asynchronous Python-RQ job, all they need is yet a different logger:\n\n.. code:: python\n\n    from proglog import RqWorkerBarLogger\n    from my_library import my_routine\n\n    logger = RqWorkerBarLogger(job=some_python_rq_job)\n    my_routine(logger=logger)\n\nThis allows to then display progress bars on the website such as these (see the `EGF CUBA \u003chttps://github.com/Edinburgh-Genome-Foundry/CUBA\u003e`_ project for an example of website using Proglog):\n\n.. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/website_bar.png\"    width=\"450\"\u003e\n    \u003c/p\u003e\n\n\nThe user may also want a custom progress logger which selectively ignores the ``animals`` progress bar, and only updates its bars every second (to save computing time):\n\n.. code:: python\n\n    from proglog import TqdmProgressBarLogger\n    from my_library import my_routine\n\n    logger = TqdmProgressBarLogger(ignored_bars=('animal',),\n                                   min_time_interval=1.0)\n    my_routine(logger=logger)\n\nProglog loggers can be used for much more than just progress bars. They can in fact store any kind of data with a simple API:\n\n.. code:: python\n\n    logger(message='Now running the main program, be patient...')\n    logger(current_animal='cat')\n    logger(last_number_tried=1235)\n\nFor more complex customization, such as adding callback functions which will be executed every time the logger's state is updated, simply create a new logger class:\n\n.. code:: python\n\n    from proglog import ProgressBarLogger\n    from my_library import my_routine\n\n    class MyBarLogger(ProgressBarLogger):\n\n        def callback(self, **changes):\n            # Every time the logger is updated, this function is called with\n            # the `changes` dictionnary of the form `parameter: new value`.\n\n            for (parameter, new_value) in changes.items():\n                print ('Parameter %s is now %s' % (parameter, value))\n\n    logger = MyBarLogger()\n    my_routine(logger=logger)\n\nWhen writing libraries which all log progress and may depend on each other, simply pass the Proglog logger from one program to its dependencies, to obtain one logger keeping track of all progress across libraries at once:\n\n.. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/Proglog/master/images/loggers_schema.png\"    width=\"650\"\u003e\n    \u003c/p\u003e\n\nNote that this implies that not two libraries use the same variables or loop names, which can be avoided by attributing prefixes to these names:\n\n.. code:: python\n\n    for i in logger.iter_bar(iteration=range(iterations), bar_prefix='libraryname_'):\n        ...\n\n\nInstallation\n------------\n\nYou can install Proglog through PIP:\n\n.. code:: shell\n\n    pip install proglog\n\nAlternatively, you can unzip the sources in a folder and type:\n\n.. code:: shell\n\n    python setup.py install\n\nTo use the ``tqdm`` notebook-style progress bars you need to install iwidgets:\n\n.. code:: shell\n\n    pip install ipywidgets\n\nThis `should automatically enable it \u003chttps://ipywidgets.readthedocs.io/en/latest/user_install.html\u003e`_; for older versions try:\n\n.. code:: shell\n\n    jupyter nbextension enable --py --sys-prefix widgetsnbextension\n\n\nLicense = MIT\n-------------\n\nProglog is an open-source software originally written at the `Edinburgh Genome Foundry\n\u003chttps://www.ed.ac.uk/biology/research/facilities/edinburgh-genome-foundry\u003e`_ by `Zulko \u003chttps://github.com/Zulko\u003e`_\nand `released on Github \u003chttps://github.com/Edinburgh-Genome-Foundry/DnaCauldron\u003e`_ under\nthe MIT license (Copyright 2017 Edinburgh Genome Foundry, University of Edinburgh).\n\nProglog was not written by loggology experts, it *just works* with our projects and we use it a lot.\nEveryone is welcome to contribute if you find bugs or limitations !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedinburgh-genome-foundry%2Fproglog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedinburgh-genome-foundry%2Fproglog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedinburgh-genome-foundry%2Fproglog/lists"}