argparse-from-file 1.0__py3-none-any.whl

argparse_from_file-1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: argparse-from-file
+Version: 1.0
+Summary: Wrapper for Python's argparse to also read arguments from a file
+Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/bulletmark/argparse-from-file
+Keywords: argparse,ConfigArgParse
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: platformdirs
+
+# ARGPARSE-FROM-FILE
+[![PyPi](https://img.shields.io/pypi/v/argparse-from-file)](https://pypi.org/project/argparse-from-file/)
+[![AUR](https://img.shields.io/aur/version/python-argparse-from-file)](https://aur.archlinux.org/packages/python-argparse-from-file/)
+
+`argparse-from-file` is a lightweight wrapper for Python's standard
+[`argparse`][argparse] module. It allows your program to read default arguments
+from a configuration file, which are prepended to arguments provided on the
+command line.
+
+The latest version of this document and code is available at
+https://github.com/bulletmark/argparse-from-file.
+
+## Features
+
+* **Drop-in replacement:** Simply change `import argparse` to `import
+  argparse_from_file as argparse`. No other code changes are needed for basic
+  functionality.
+* **Automatic configuration:** By default, it loads arguments from
+  `<program_name>-flags.conf` in the user's configuration directory (e.g.,
+  `~/.config/` on Linux). The exact path is determined using the
+  [`platformdirs`][platformdirs] library to respect OS conventions.
+* **Custom configuration file:** Specify a custom file path with the
+  `from_file` argument to [`ArgumentParser()`][argparser].
+* **Simple file format:** The configuration file is a simple text file with
+  options specified on one or more lines. Blank lines and lines starting with
+  `#` are ignored.
+* **Informative help text:** The program's help message is automatically
+  updated to show the path to the configuration file.
+
+## Usage
+
+To get started, replace the standard [`argparse`][argparse] import in your project:
+
+```python
+# import argparse
+import argparse_from_file as argparse
+```
+
+That's it! Your application will now automatically look for a default
+configuration file and use the default arguments provided therein.
+
+To specify a custom configuration file, use the `from_file` keyword argument,
+which is the only addition to the standard
+[`ArgumentParser()`][argparser] API:
+
+```python
+# Use a specific file path
+parser = argparse.ArgumentParser(from_file='/path/to/my/config', ..)
+
+# Use a file relative to the user's config directory
+parser = argparse.ArgumentParser(from_file='my-app.conf', ..)
+```
+
+The `from_file` argument accepts a string or a [`pathlib.Path`][pathlib].
+Relative paths are resolved relative to the user's configuration directory as
+determined by `platformdirs`.
+
+## Configuration File Format
+
+Arguments in the configuration file are best specified one per line so they can
+easily be commented out. It is also recommended to use long-form options for
+clarity.
+
+Example `~/.config/myprog-flags.conf`:
+```
+--verbose
+
+# Always run with foo set to 123
+--foo 123
+```
+
+## Customizing the Help Message
+
+`argparse-from-file` automatically adds an `epilog` to the help message
+indicating the configuration file path. If you instead provide a custom `epilog`
+(or `usage` or `description`), you can embed the `#FROM_FILE_PATH#` placeholder,
+and it will be replaced with the actual path used.
+
+## Example
+
+Here is a simple example program (`myprog.py`):
+
+```python
+#!/usr/bin/python3
+import argparse_from_file as argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--foo', type=int, default=42, help='foo help')
+opts = parser.parse_args()
+
+print(f"foo is: {opts.foo}")
+```
+
+If `~/.config/myprog-flags.conf` contains `--foo=123`, the output is:
+
+```
+$ python myprog.py
+foo is: 123
+```
+
+The help text (`epilog`) is also automatically added as seen below:
+```
+$ python myprog.py -h
+usage: myprog.py [-h] [--foo FOO]
+
+options:
+  -h, --help  show this help message and exit
+  --foo FOO   foo help
+
+Note you can set default starting options in /home/user/.config/myprog-flags.conf.
+```
+
+## Installation
+
+Arch Linux users can install `python-argparse-from-file` from the
+[AUR](https://aur.archlinux.org/packages/python-argparse-from-file/).
+
+Alternatively, `argparse-from-file` is available on
+[PyPI](https://pypi.org/project/argparse-from-file/) and can be installed with
+pip:
+
+```bash
+pip install argparse-from-file
+```
+
+## License
+
+Copyright (C) 2025 Mark Blakeney. This program is distributed under the terms
+of the GNU General Public License. This program is free software: you can
+redistribute it and/or modify it under the terms of the GNU General Public
+License as published by the Free Software Foundation, either version 3 of the
+License, or any later version. This program is distributed in the hope that it
+will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
+License at <https://opensource.org/license/gpl-3-0> for more details.
+
+[argparse]: https://docs.python.org/3/library/argparse.html
+[platformdirs]: https://github.com/tox-dev/platformdirs
+[argparser]: https://docs.python.org/3/library/argparse.html#argumentparser-objects
+[pathlib]: https://docs.python.org/3/library/pathlib.html
+<!-- vim: se ai syn=markdown: -->

argparse_from_file-1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+argparse_from_file.py,sha256=19CjAx6MZZgdtHrY-Brl7z7F5M7OwofBGymRRDGpKpk,2724
+argparse_from_file-1.0.dist-info/METADATA,sha256=ZHwjobsEsXjG7c4vcmIL31AVfXVF_3ZxID7oz2kfmpE,5420
+argparse_from_file-1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+argparse_from_file-1.0.dist-info/top_level.txt,sha256=8JxJArcqZ5CZzytAonnblZ3Y8-zq2DDZXYzcTJf9k70,19
+argparse_from_file-1.0.dist-info/RECORD,,

argparse_from_file-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

argparse_from_file-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+argparse_from_file

argparse_from_file.py

@@ -0,0 +1,72 @@
+"""
+A very light wrapper around Python's argparse module to prepend a program's
+argument list with default options and arguments read from a user configuration
+file.
+"""
+
+import argparse
+import shlex
+import sys
+from pathlib import Path
+
+import platformdirs
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args, **kwargs):
+        self._argv = []
+
+        # from_file = 'path-to/file': Use this as "from file" name/path. If
+        #   relative then wrt platform specific user config dir.
+        # from_file = '': Do not use a "from file".
+        # from_file = None: Create default "from file" path.
+        if (from_file := kwargs.pop('from_file', None)) is None:
+            from_file = Path(sys.argv[0]).stem + '-flags.conf'
+
+        if from_file:
+            from_file_path = platformdirs.user_config_path(from_file)
+            from_file_path_str = str(from_file_path)
+            # epilog = 'text string': Set this as epilog, replacing any
+            #   '#FROM_FILE_PATH#' with the above determined "from file" path.
+            # epilog = '': Do not set an epilog.
+            # epilog = None: create default epilog with "from file" path.
+            if (epilog := kwargs.pop('epilog', None)) is None:
+                epilog = f'Note you can set default starting options in {from_file_path_str}.'
+            else:
+                epilog = epilog.replace('#FROM_FILE_PATH#', from_file_path_str)
+
+            if epilog:
+                kwargs['epilog'] = epilog
+
+            # Also replace any '#FROM_FILE_PATH#' in usage and description.
+            for kw in 'usage', 'description':
+                if v := kwargs.get(kw):
+                    kwargs[kw] = v.replace('#FROM_FILE_PATH#', from_file_path_str)
+
+            # Create list of default args from user file.
+            if from_file_path.is_file():
+                with from_file_path.open() as fp:
+                    self._argv.extend(
+                        ln
+                        for line in fp
+                        if (ln := line.strip()) and not ln.startswith('#')
+                    )
+        else:
+            from_file_path = None
+
+        self.from_file_path = from_file_path
+        return super().__init__(*args, **kwargs)
+
+    def parse_args(self, args=None, namespace=None):  # type: ignore[override]
+        if args is None and self._argv:
+            # Combine args from file and command line, to be parsed
+            argstr = ' '.join(self._argv).strip()
+            args = shlex.split(argstr) + sys.argv[1:]
+
+        del self._argv
+        return super().parse_args(args, namespace)
+
+
+def __getattr__(name: str):
+    "Proxy all other attributes from argparse module."
+    return getattr(argparse, name)