Metadata-Version: 2.1
Name: argparse-history
Version: 0.1.2
Summary: An extension of argparse with history tracking
Home-page: https://github.com/dimitrix-cnrs/argparse-history
Author: Dimitry Khvorostyanov
Author-email: dimitry.khvorostyanov@locean.ipsl.fr
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# 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-stats
```

In addition to the arguments history this will display any data saved during program runs.


#### 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
```

### Adding your script performance statistics

```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)
```

## Why Choose argparse_h?

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!
