# argparse-history
## Why Track Command History?
Have you ever found yourself wondering:
- "What parameters did I use for that successful run last week?"
- "How can I replicate the exact configuration from my previous experiments?"
- "Is there an easy way to audit how my script has been used over time?"
- "How can I track my program's performance changes depending on its parameters?"
`argparse-history` is here to solve these problems and more!
## What is `argparse-history`?
`argparse_h.ArgumentParser` is an extension of Python's built-in `argparse.ArgumentParser` that automatically tracks and stores the command-line arguments used in your scripts. It's designed to be a drop-in replacement for ArgumentParser, adding powerful history tracking capabilities with minimal changes to your existing code.
## Key Features
- 📜 Automatic command history tracking
- 🕰️ Timestamped entries for easy reference
- 🔍 Built-in history viewing functionality
- 🔍 Tracking execution statistics, or any other relevant data depending on the arguments
- 📁 Customizable history file location
- 🔌 Seamless integration with existing argparse code
## Installation
Install `argparse-history` with pip:
```bash
pip install argparse-history
```
## Quick Start
Replace your existing `ArgumentParser` with `argparse_h.ArgumentParser`:
```python
from argparse_h import ArgumentParser
parser = ArgumentParser(description="Your script description")
parser.add_argument('--input', help='Input file', required=True)
parser.add_argument('--output', help='Output file', required=True)
args = parser.parse_args()
# Your script logic here
```
That's it! Your script now tracks command history automatically.
### Viewing Command History
To view the command history, simply run your script with the --show-history flag:
```bash
python your_script.py --show-history
```
This will display a list of previous runs with their timestamps and arguments.
```bash
python your_script.py --show-args "2024-10-04T10:30:00"
```
This will display the command line that corresponds to the timestamp `"2024-10-04T10:30:00"`
(that you hopefully copy-pasted from `--show-history` output!)
```bash
python your_script.py --show-stats
```
In addition to the arguments history this will display any data saved during program runs (see below
how to add your performance data to the history).
#### Customizing History File Location
By default, the history is stored in the current directory. You can specify a custom directory:
```bash
python your_script.py --input in.txt --output out.txt --history-dir /path/to/history
```
### Play with the provided example!
#### Basic usage:
```bash
python test_argparse.py 80 -n 42 -s hello --flag -l item1 -l item2
```
- should yield:
```bash
Parsed arguments:
m: 80
-n: 42
-s: hello
-c: None
--flag: True
-l: ['item1', 'item2']
Computation result: 1764
```
#### Show history:
```bash
python test_argparse.py --show-history
```
- gives something like:
```bash
Timestamp: 2024-10-05T00:20:36
Arguments:
m: 80
-n: 42
-s: hello
-c: None
--flag: True
-l: ['item1', 'item2']
Timestamp: 2024-10-05T00:23:19
Arguments:
m: 80
-n: 42
-s: hello
-c: OASIS8
--flag: True
-l: ['item1', 'item2']
```
#### Show stats:
```bash
python test_argparse.py --show-stats
```
- yields something like:
```bash
Timestamp: 2024-10-05T00:20:36
Arguments:
m: 80
-n: 42
-s: hello
-c: None
--flag: True
-l: ['item1', 'item2']
Statistics:
execution_time: 1.5s
memory_usage: 100MB
Timestamp: 2024-10-05T00:23:19
Arguments:
m: 80
-n: 42
-s: hello
-c: OASIS8
--flag: True
-l: ['item1', 'item2']
Statistics:
execution_time: 1.5s
memory_usage: 100MB
```
#### Show args: print all arguments for a case as a command line
- Show the command line for a particular case (given by its timestamp), so that you are ready to execute
the same configuration:
```bash
python test_argparse.py --show-args 2024-10-05T00:23:19
```
- yields:
```bash
80 -n 42 -s hello -c OASIS8 --flag -l item1 -l item2
````
- And you just copy-paste these after your script's name if you want to use exactly the same arguments:
```bash
python test_argparse.py 80 -n 42 -s hello -c OASIS8 --flag -l item1 -l item2
````
### How to add your script performance statistics?
- Just call `parser.add_data()` with a dictionary of parameters to save! This is how
it is done in the example script:
```python
from argparse_h import ArgumentParser
...
# Simulate adding some stats
parser.add_data({"execution_time": "1.5s", "memory_usage": "100MB"})
```
- For a slightly more complex example within a class:
```python
from argparse_h import ArgumentParser
class MyProcessorClass:
# your class methods....
def process(self):
# Perform operations
# .....
self.execution_data = {'n_procs': n_procs, 'cpu time': cpu_time, 'elapsed time': elapsed_time}
# ......
if __name__ == '__main__':
# .....
parser = ArgumentParser(...)
# ....
processor = MyProcessorClass(...)
processor.process()
# ....
parser.add_data(processor.execution_data)
```
After you run your script, this will allow you to run:
```bash
python your_script.py --show-stats
```
and to track your performance data depending on the script arguments.
## Why Choose argparse-history?
1. Effortless Integration: Minimal changes to your existing code.
2. Improved Reproducibility: Easily recreate previous runs.
3. Better Debugging: Quickly identify what parameters were used in past executions.
4. Audit Trail: Keep track of how and when your script is being used.
5. Execution statistics: keep track of your script performance, or any other relevant data, depending on its parameters.
5. Time-Saving: No more manual logging of script parameters.
## Contributing
Your contributions are welcome! Please feel free to share if you use `argparse-history` and how it is useful to you.
Also let me know if you have any suggestions of how it could serve you even better!
## License
This project is licensed under the MIT License - see the LICENSE file for details. Start tracking your command history today with argparse_h!
## Functional requirements
- The arguments 'show_history', 'show_stats', 'show_args', 'history_dir' are not recorded to history
- The arguments 'show_history', 'show_stats', 'show_args', 'history_dir' are not listed by the class method
`print_args()`
- If one of ['show_history', 'show_stats', 'show_args', 'history_dir'] is provided the program stops after
performing the corresponding actions
- Arguments are stored in their short form
- Arguments are shown by `--show-args` with their leading '-', so that the command line is ready for execution
- Positional (mandatory) arguments are listed by show_args() without their names, just values
Raw data
{
"_id": null,
"home_page": "https://github.com/dimitrix-cnrs/argparse-history",
"name": "argparse-history",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "argparse history command-line",
"author": "Dimitry Khvorostyanov",
"author_email": "dimitry.khvorostyanov@locean.ipsl.fr",
"download_url": "https://files.pythonhosted.org/packages/26/e4/63c53b33af966a6fa215e9972de2cf323c4f54b85bc7fc8242edb744d723/argparse_history-0.2.5.tar.gz",
"platform": null,
"description": "# argparse-history\n\n## Why Track Command History?\n\nHave you ever found yourself wondering:\n- \"What parameters did I use for that successful run last week?\"\n- \"How can I replicate the exact configuration from my previous experiments?\"\n- \"Is there an easy way to audit how my script has been used over time?\"\n- \"How can I track my program's performance changes depending on its parameters?\"\n\n`argparse-history` is here to solve these problems and more!\n\n## What is `argparse-history`?\n\n`argparse_h.ArgumentParser` is an extension of Python's built-in `argparse.ArgumentParser` that automatically tracks and stores the command-line arguments used in your scripts. It's designed to be a drop-in replacement for ArgumentParser, adding powerful history tracking capabilities with minimal changes to your existing code.\n\n## Key Features\n\n- \ud83d\udcdc Automatic command history tracking\n- \ud83d\udd70\ufe0f Timestamped entries for easy reference\n- \ud83d\udd0d Built-in history viewing functionality\n- \ud83d\udd0d Tracking execution statistics, or any other relevant data depending on the arguments\n- \ud83d\udcc1 Customizable history file location\n- \ud83d\udd0c Seamless integration with existing argparse code\n\n## Installation\n\nInstall `argparse-history` with pip:\n\n```bash\npip install argparse-history\n```\n\n## Quick Start\nReplace your existing `ArgumentParser` with `argparse_h.ArgumentParser`:\n\n```python\nfrom argparse_h import ArgumentParser\n\nparser = ArgumentParser(description=\"Your script description\")\nparser.add_argument('--input', help='Input file', required=True)\nparser.add_argument('--output', help='Output file', required=True)\n\nargs = parser.parse_args()\n\n# Your script logic here\n\n```\n\nThat's it! Your script now tracks command history automatically.\n\n### Viewing Command History\nTo view the command history, simply run your script with the --show-history flag:\n\n```bash\npython your_script.py --show-history\n```\n\nThis will display a list of previous runs with their timestamps and arguments.\n\n```bash\npython your_script.py --show-args \"2024-10-04T10:30:00\"\n```\n\nThis will display the command line that corresponds to the timestamp `\"2024-10-04T10:30:00\"` \n(that you hopefully copy-pasted from `--show-history` output!)\n\n```bash\npython your_script.py --show-stats\n```\n\nIn addition to the arguments history this will display any data saved during program runs (see below\nhow to add your performance data to the history).\n\n\n#### Customizing History File Location\n\nBy default, the history is stored in the current directory. You can specify a custom directory:\n\n```bash\npython your_script.py --input in.txt --output out.txt --history-dir /path/to/history\n```\n\n### Play with the provided example!\n\n#### Basic usage:\n\n```bash\npython test_argparse.py 80 -n 42 -s hello --flag -l item1 -l item2\n```\n\n- should yield:\n\n```bash\nParsed arguments:\n m: 80\n -n: 42\n -s: hello\n -c: None\n --flag: True\n -l: ['item1', 'item2']\n\nComputation result: 1764\n```\n\n#### Show history:\n```bash\npython test_argparse.py --show-history\n```\n\n- gives something like:\n\n```bash\nTimestamp: 2024-10-05T00:20:36\nArguments:\n m: 80\n -n: 42\n -s: hello\n -c: None\n --flag: True\n -l: ['item1', 'item2']\n\nTimestamp: 2024-10-05T00:23:19\nArguments:\n m: 80\n -n: 42\n -s: hello\n -c: OASIS8\n --flag: True\n -l: ['item1', 'item2']\n```\n\n#### Show stats:\n```bash\npython test_argparse.py --show-stats\n```\n\n- yields something like:\n\n```bash\nTimestamp: 2024-10-05T00:20:36\nArguments:\n m: 80\n -n: 42\n -s: hello\n -c: None\n --flag: True\n -l: ['item1', 'item2']\nStatistics:\n execution_time: 1.5s\n memory_usage: 100MB\n\nTimestamp: 2024-10-05T00:23:19\nArguments:\n m: 80\n -n: 42\n -s: hello\n -c: OASIS8\n --flag: True\n -l: ['item1', 'item2']\nStatistics:\n execution_time: 1.5s\n memory_usage: 100MB\n```\n\n#### Show args: print all arguments for a case as a command line\n\n- Show the command line for a particular case (given by its timestamp), so that you are ready to execute \nthe same configuration:\n\n```bash\npython test_argparse.py --show-args 2024-10-05T00:23:19\n```\n\n- yields:\n\n```bash\n80 -n 42 -s hello -c OASIS8 --flag -l item1 -l item2\n````\n\n- And you just copy-paste these after your script's name if you want to use exactly the same arguments: \n\n```bash\npython test_argparse.py 80 -n 42 -s hello -c OASIS8 --flag -l item1 -l item2\n````\n\n\n### How to add your script performance statistics?\n\n- Just call `parser.add_data()` with a dictionary of parameters to save! This is how \nit is done in the example script: \n\n```python\nfrom argparse_h import ArgumentParser\n...\n# Simulate adding some stats\nparser.add_data({\"execution_time\": \"1.5s\", \"memory_usage\": \"100MB\"})\n```\n\n- For a slightly more complex example within a class:\n\n```python\nfrom argparse_h import ArgumentParser\n\n\nclass MyProcessorClass:\n # your class methods....\n def process(self):\n # Perform operations\n # .....\n self.execution_data = {'n_procs': n_procs, 'cpu time': cpu_time, 'elapsed time': elapsed_time}\n\n # ......\n\n\nif __name__ == '__main__':\n # .....\n parser = ArgumentParser(...)\n # ....\n processor = MyProcessorClass(...)\n processor.process()\n # ....\n parser.add_data(processor.execution_data)\n```\n\nAfter you run your script, this will allow you to run: \n```bash\npython your_script.py --show-stats\n```\nand to track your performance data depending on the script arguments. \n\n\n## Why Choose argparse-history?\n\n1. Effortless Integration: Minimal changes to your existing code.\n2. Improved Reproducibility: Easily recreate previous runs.\n3. Better Debugging: Quickly identify what parameters were used in past executions.\n4. Audit Trail: Keep track of how and when your script is being used.\n5. Execution statistics: keep track of your script performance, or any other relevant data, depending on its parameters.\n5. Time-Saving: No more manual logging of script parameters.\n\n## Contributing\nYour contributions are welcome! Please feel free to share if you use `argparse-history` and how it is useful to you. \nAlso let me know if you have any suggestions of how it could serve you even better!\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details. Start tracking your command history today with argparse_h!\n\n## Functional requirements\n\n- The arguments 'show_history', 'show_stats', 'show_args', 'history_dir' are not recorded to history\n- The arguments 'show_history', 'show_stats', 'show_args', 'history_dir' are not listed by the class method\n`print_args()` \n- If one of ['show_history', 'show_stats', 'show_args', 'history_dir'] is provided the program stops after \nperforming the corresponding actions\n- Arguments are stored in their short form\n- Arguments are shown by `--show-args` with their leading '-', so that the command line is ready for execution\n- Positional (mandatory) arguments are listed by show_args() without their names, just values\n",
"bugtrack_url": null,
"license": null,
"summary": "An extension of argparse with history tracking",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/dimitrix-cnrs/argparse-history"
},
"split_keywords": [
"argparse",
"history",
"command-line"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2c5e68d303ab857d48acaf8e877c876a92280d58eecdc124eb91c62519bbbab",
"md5": "87fd5afa07a3759edc280d1e8397a39a",
"sha256": "bc6580426def18036568907606b8d1875a8badf976e43a044e1f9298e179f2a4"
},
"downloads": -1,
"filename": "argparse_history-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87fd5afa07a3759edc280d1e8397a39a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6877,
"upload_time": "2024-10-04T22:38:38",
"upload_time_iso_8601": "2024-10-04T22:38:38.693963Z",
"url": "https://files.pythonhosted.org/packages/c2/c5/e68d303ab857d48acaf8e877c876a92280d58eecdc124eb91c62519bbbab/argparse_history-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26e463c53b33af966a6fa215e9972de2cf323c4f54b85bc7fc8242edb744d723",
"md5": "7e65458238993f30f6f04c4a04c1dc5a",
"sha256": "d4bbb4156d85314aadcf0ed107b758d220bae1625b19c6de6699fd93c3bf5996"
},
"downloads": -1,
"filename": "argparse_history-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "7e65458238993f30f6f04c4a04c1dc5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6655,
"upload_time": "2024-10-04T22:38:40",
"upload_time_iso_8601": "2024-10-04T22:38:40.633981Z",
"url": "https://files.pythonhosted.org/packages/26/e4/63c53b33af966a6fa215e9972de2cf323c4f54b85bc7fc8242edb744d723/argparse_history-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 22:38:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dimitrix-cnrs",
"github_project": "argparse-history",
"github_not_found": true,
"lcname": "argparse-history"
}
JSON
