Skip to main content

An extension of argparse with history tracking

Project description

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:

pip install argparse-history

Quick Start

Replace your existing ArgumentParser with argparse_h.ArgumentParser:

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:

python your_script.py --show-history

This will display a list of previous runs with their timestamps and arguments.

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

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:

python your_script.py --input in.txt --output out.txt --history-dir /path/to/history

Play with the provided example!

Basic usage:

python test_argparse.py 80 -n 42 -s hello --flag -l item1 -l item2
  • should yield:
Parsed arguments:
  m: 80
  -n: 42
  -s: hello
  -c: None
  --flag: True
  -l: ['item1', 'item2']

Computation result: 1764

Show history:

python test_argparse.py --show-history
  • gives something like:
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:

python test_argparse.py --show-stats
  • yields something like:
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:
python test_argparse.py --show-args 2024-10-05T00:23:19
  • yields:
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:
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:
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:
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:

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.
  6. 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

argparse_history-0.2.5.tar.gz (6.7 kB view details)

Uploaded Source

Built Distribution

argparse_history-0.2.5-py3-none-any.whl (6.9 kB view details)

Uploaded Python 3

File details

Details for the file argparse_history-0.2.5.tar.gz.

File metadata

  • Download URL: argparse_history-0.2.5.tar.gz
  • Upload date:
  • Size: 6.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for argparse_history-0.2.5.tar.gz
Algorithm Hash digest
SHA256 d4bbb4156d85314aadcf0ed107b758d220bae1625b19c6de6699fd93c3bf5996
MD5 7e65458238993f30f6f04c4a04c1dc5a
BLAKE2b-256 26e463c53b33af966a6fa215e9972de2cf323c4f54b85bc7fc8242edb744d723

See more details on using hashes here.

File details

Details for the file argparse_history-0.2.5-py3-none-any.whl.

File metadata

File hashes

Hashes for argparse_history-0.2.5-py3-none-any.whl
Algorithm Hash digest
SHA256 bc6580426def18036568907606b8d1875a8badf976e43a044e1f9298e179f2a4
MD5 87fd5afa07a3759edc280d1e8397a39a
BLAKE2b-256 c2c5e68d303ab857d48acaf8e877c876a92280d58eecdc124eb91c62519bbbab

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page