{"id":16518484,"url":"https://github.com/valentingol/logml","last_synced_at":"2025-10-28T07:30:25.510Z","repository":{"id":156789065,"uuid":"633037440","full_name":"valentingol/logml","owner":"valentingol","description":"Log your ml training in the console in an attractive way.","archived":false,"fork":false,"pushed_at":"2024-01-09T14:21:07.000Z","size":29269,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-13T12:51:58.506Z","etag":null,"topics":["deep-learning","deeplearning","log","logger","logging","machine-learning","machinelearning"],"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/valentingol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2023-04-26T16:38:55.000Z","updated_at":"2024-04-03T15:37:55.000Z","dependencies_parsed_at":"2024-01-08T15:13:37.143Z","dependency_job_id":"d0b5ccad-f8df-4b93-8948-50c09ad94598","html_url":"https://github.com/valentingol/logml","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valentingol%2Flogml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valentingol%2Flogml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valentingol%2Flogml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valentingol%2Flogml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valentingol","download_url":"https://codeload.github.com/valentingol/logml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219860032,"owners_count":16556029,"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":["deep-learning","deeplearning","log","logger","logging","machine-learning","machinelearning"],"created_at":"2024-10-11T16:36:16.292Z","updated_at":"2025-10-28T07:30:19.898Z","avatar_url":"https://github.com/valentingol.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# LoggerML - Rich machine learning logger in the console\n\nLog your Machine Learning training in the console in a beautiful way using\n[rich](https://github.com/Textualize/rich)✨ with useful information but with\nminimal code.\n\n## Documentation [here](https://logml.readthedocs.io/en/latest/)\n\n---\n\n[![PyPI version](https://badge.fury.io/py/loggerml.svg)](https://badge.fury.io/py/loggerml)\n![PythonVersion](https://img.shields.io/badge/python-3.7%20%7E%203.11-informational)\n[![License](https://img.shields.io/github/license/valentingol/logml?color=999)](https://stringfixer.com/fr/MIT_license)\n\n[![Ruff_logo](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)\n[![Black_logo](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n[![Ruff](https://github.com/valentingol/logml/actions/workflows/ruff.yaml/badge.svg)](https://github.com/valentingol/logml/actions/workflows/ruff.yaml)\n[![Flake8](https://github.com/valentingol/logml/actions/workflows/flake.yaml/badge.svg)](https://github.com/valentingol/logml/actions/workflows/flake.yaml)\n[![Pydocstyle](https://github.com/valentingol/logml/actions/workflows/pydocstyle.yaml/badge.svg)](https://github.com/valentingol/logml/actions/workflows/pydocstyle.yaml)\n[![MyPy](https://github.com/valentingol/logml/actions/workflows/mypy.yaml/badge.svg)](https://github.com/valentingol/logml/actions/workflows/mypy.yaml)\n[![PyLint](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/valentingol/451f91cece4478ebc81377e27e432f8b/raw/logml_pylint.json)](https://github.com/valentingol/logml/actions/workflows/pylint.yaml)\n\n[![Tests](https://github.com/valentingol/logml/actions/workflows/tests.yaml/badge.svg)](https://github.com/valentingol/logml/actions/workflows/tests.yaml)\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/valentingol/451f91cece4478ebc81377e27e432f8b/raw/logml_tests.json)](https://github.com/valentingol/logml/actions/workflows/tests.yaml)\n[![Documentation Status](https://readthedocs.org/projects/logml/badge/?version=latest)](https://logml.readthedocs.io/en/latest/?badge=latest)\n\n## Installation\n\nIn a new virtual environment, install simply the package via\n[pipy](https://pypi.org/project/loggerml/):\n\n```bash\npip install loggerml\n```\n\nThis package is supported on Linux, macOS and Windows.\nIt is also supported on Jupyter Notebooks.\n\n## Quick start\n\n### Minimal usage\n\nIntegrate the LogML logger in your training loops! For instance for 4 epochs\nand 20 batches per epoch:\n\n```python\nimport time\n\nfrom logml import Logger\n\nlogger = Logger(n_epochs=4, n_batches=20)\n\nfor _ in range(4):\n    for _ in logger.tqdm(range(20)):\n        time.sleep(0.1)  # Simulate a training step\n        # Log whatever you want (int, float, str, bool):\n        logger.log({\n            'loss': 0.54321256,\n            'accuracy': 0.85244777,\n            'loss name': 'MSE',\n            'improve baseline': True,\n        })\n```\n\nYields:\n\n![base-gif](https://raw.githubusercontent.com/valentingol/logml/main/docs/_static/base.gif))\n\nNote that the expected remaining time of the overall train is displayed as well as\nthe one for the epoch. The logger also provides also the possibility to average the\nlogged values over an epoch or a full training.\n\n### Pause and resume\n\nYou can also pause and resume the logger internal time with `logger.pause()` and\n`logger.resume()`. You can check the internal time with `logger.get_current_time()`.\nNote that the resume method continues the time from **the last pause**.\nit means that if you pause the training logger at 10 seconds, then resume it\nat 20 seconds, the logger will display 10 seconds of training time. The global and\nthe epoch time will be updated accordingly. You can also find examples in\nthe documentation.\n\n### Save the logs\n\nIn Linux you can use `tee` to save the logs in a file and display them in the console.\nHowever you need to use `unbuffer` to keep the style:\n\n```bash\nunbuffer python main.py --color=auto | tee output.log\n```\n\nSee\n[here](https://superuser.com/questions/352697/preserve-colors-while-piping-to-tee)\nfor details.\n\n### Advanced usage\n\nNow you can add a validation logger, customize the logger with your own styles\nand colors, compute the average of some values over batch, add a dynamic\nmessage at each batch, update the value only every some batches and more!\n\nAt initialization you can set default configuration for the logger that will be\neventually overwritten by the configuration passed to the `log` method.\n\nAn example with more features:\n\n```python\ntrain_logger = Logger(\n    n_epochs=2,\n    n_batches=20,\n    log_interval=2,\n    name='Training',\n    name_style='dark_orange',\n    styles='yellow',  # Default style for all values\n    sizes={'accuracy': 4},  # only 4 characters for 'accuracy'\n    average=['loss'],  # 'loss' will be averaged over the current epoch\n    bold_keys=True,  # Bold the keys\n)\nval_logger = Logger(\n    n_epochs=2,\n    n_batches=10,\n    name='Validation',\n    name_style='cyan',\n    styles='blue',\n    bold_keys=True,\n    show_time=False,  # Remove the time bar\n)\nfor _ in range(2):\n    train_logger.new_epoch()  # Manually declare a new epoch\n    for _ in range(20):\n        train_logger.new_batch()  # Manually declare a new batch\n        time.sleep(0.1)\n        # Overwrite the default style for \"loss\" and add a message\n        train_logger.log(\n            {'loss': 0.54321256, 'accuracy': 85.244777},\n            styles={'loss': 'italic red'},\n            message=\"Training is going well?\\nYes!\",\n        )\n    val_logger.new_epoch()\n    for _ in range(10):\n        val_logger.new_batch()\n        time.sleep(0.1)\n        val_logger.log({'val loss': 0.65422135, 'val accuracy': 81.2658775})\n    val_logger.detach()  # End the live display to print something else after\n```\n\nYields:\n\n![Alt Text](https://raw.githubusercontent.com/valentingol/logml/main/docs/_static/advanced.gif)\n\n### Don't know the number of batches in advance?\n\nIf you don't have the number of batches in advance, you can initialize the logger\nwith `n_batches=None`. Only the available information will be displayed. For instance\nwith the configuration of the first example:\n\n![Alt Text](https://raw.githubusercontent.com/valentingol/logml/main/docs/_static/no_n_batches.png)\n\nThe progress bar is replaced by a cyclic animation. The eta times are not know at the\nfirst epoch but was estimated after the second epoch.\n\nNote that if you use `Logger.tqdm(dataset)` and the dataset has a length, the number of\nbatches will be automatically set to the length of the dataset.\n\n## How to contribute\n\nFor **development**, install the package dynamically and dev requirements with:\n\n```bash\npip install -e .\npip install -r requirements-dev.txt\n```\n\nEveryone can contribute to LogML, and we value everyone’s contributions.\nPlease see our [contributing guidelines](CONTRIBUTING.md) for more information 🤗\n\n### Todo\n\nTo do:\n\nDone:\n\n- [x] Allow multiple logs on the same batch\n- [x] Finalize tests for 1.0.0 major release\n- [x] Add docs sections: comparison with tqdm and how to use mean_vals\n  (with exp tracker)\n- [x] Use regex for `styles`, `sizes` and `average` keys\n- [x] Be compatible with notebooks\n- [x] Get back the cursor when interrupting the training\n- [x] `logger.tqdm()` feature (used like `tqdm.tqdm`)\n- [x] Doc with Sphinx\n- [x] Be compatible with Windows and Macs\n- [x] Manage a validation loop (then multiple loggers)\n- [x] Add color customization for message, epoch/batch number and time\n- [x] Add pause/resume feature\n\n## License\n\nCopyright (C) 2023  Valentin Goldité\n\nThis program is free software: you can redistribute it and/or modify it under the\nterms of the [MIT License](LICENSE). This program is distributed in the hope that\nit will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\nThis project is free to use for COMMERCIAL USE, MODIFICATION, DISTRIBUTION and\nPRIVATE USE as long as the original license is include as well as this copy\nright notice at the top of the modified files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalentingol%2Flogml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalentingol%2Flogml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalentingol%2Flogml/lists"}