release: v0.0.1

Author: ThomasAtlantis

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+/dist
+/*.egg-info/
+/build

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shangyu Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,80 @@
+# xparameter
+A portable configuration tool to manage hyperparameters and settings of your experiments.
+
+## Features
+:white_check_mark: Support syntax highlighting and autocompletion for attributes  
+:white_check_mark: Support arguments control through command line  
+:white_check_mark: Support nested definition (namespaces) to isolate parameters of the same name  
+:white_check_mark: Inherent Singleton ensuring consistent revision across files  
+:white_check_mark: Support basic type checking  
+
+## Quickstart
+You can install the latest official version of xparameter from PyPI:
+
+```haskell
+pip install xparameter
+```
+
+### Define Custom Configuration
+```python
+# config.py
+from xparameter import Configure as C
+from xparameter import Field as F
+
+class Config(C):
+    """Define your overall description here"""
+
+    class checkpoint(C):
+        """Define group description here"""
+        directory       = F(str,   default="./checkpoints", help="Directory to save model checkpoints")
+
+```
+
+### Parse Command-line Arguments
+```haskell
+Config.parse_sys_args()
+```
+
+Parameters in `Config` class will be automatically registered onto a `argparse.ArgumentParser()`, which acts as a parser to extract parameter values from command line. In this example case, we use
+
+```haskell
+python test.py --checkpoint.directory "/path/to/checkpoints"
+```
+
+The argument `Config.checkpoint.directory` will be set to `"/path/to/checkpoints"`. This parsing process and the following manual revision will trigger an inherent type check.
+
+Use the `help` command to print automatically generated help menu:
+```haskell
+python test.py --help
+```
+```yaml
+Usage: config_01.py [-h] [--checkpoint.directory str]
+
+Define your overall description here
+
+Options:
+  -h, --help                  show this help message and exit
+
+Checkpoint:
+  Define group description here
+
+  --checkpoint.directory str  Directory to save model checkpoints
+```
+
+### Revise Arguments Manually
+Manual revision of the argument values can be performed either independently or as a post-processing step following the aforementioned command-line parsing, e.g.,
+
+```haskell
+# Config.parse_sys_args()
+Config.checkpoint.directory = "/path/to/checkpoints"
+```
+
+### Export as Different Formats
+Export as python dict:
+```haskell
+Config.as_dict()
+```
+Export as json string:
+```haskell
+Config.as_json()
+```

examples/config_00.py

@@ -0,0 +1,42 @@
+from xparameter.xparameter import Configure as C
+from xparameter.xparameter import Field as F
+
+
+class ObjectDetectionConfig(C):
+    """Configurations for experiments on object detection"""
+
+    class checkpoint(C):
+        """Checkpoint configuration"""
+        directory       = F(str,   default="./checkpoints", help="Directory to save model checkpoints")
+
+    class logging(C): 
+        """Logging configuration"""
+        directory       = F(str,   default="./log",         help="Log file directory")
+
+    class train(C):
+        """Training configuration"""
+        optimizer       = F(str,   default='SGD',           help="Optimizer class for model training")
+        learning_rate   = F(float, default=0.5,             help="Learning rate")
+        gamma           = F(float, default=0.2,             help="Reduction factor of learning rate")
+        num_epochs      = F(int,   default=100,             help="Number of epochs")
+        milestones      = F(tuple, default=(50, 70, 80),    help="Epoch milestones at which the learning rate is reduced by gamma")
+        weight_decay    = F(float, default=1e-5,            help="Weight decay for Adam optimizer")
+        momentum        = F(float, default=0.9,             help="Momentum for Adam optimizer")
+        batch_size      = F(int,   default=256,             help="Batch size of training samples")
+    
+    class test(C):
+        """Testing configuration"""
+        batch_size      = F(int,   default=256,             help="Batch size")
+        num_samples     = F(int,   default=1000,            help="Number of samples for testing")
+        dataset         = F(str,   default="coco",          help="Dataset name")
+
+    class common(C):
+        """Shared configuration"""
+        device          = F(str,   default="cuda:0",        help="Device to use: cpu or cuda:0/cuda:1")
+        random_seed     = F(int,   default=0,               help="Random seed to enhance reproducibility")
+
+if __name__ == "__main__":
+    config = ObjectDetectionConfig
+    config.parse_sys_args()
+    config.common.random_seed = 42
+    print(config.as_json())

examples/config_01.py

@@ -0,0 +1,13 @@
+# config.py
+from xparameter.xparameter import Configure as C
+from xparameter.xparameter import Field as F
+
+class Config(C):
+    """Define your overall description here"""
+
+    class checkpoint(C):
+        """Define group description here"""
+        directory       = F(str,   default="./checkpoints", help="Directory to save model checkpoints")
+
+if __name__ == "__main__":
+    Config.parse_sys_args()

setup.py

@@ -0,0 +1,25 @@
+import setuptools
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    name="xparameter",
+    version="0.0.1",
+    author="Shangyu Liu",
+    author_email="[email protected]",
+    description="A portable configuration tool to manage hyperparameters and settings of your experiments.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/ThomasAtlantis/xparameter",
+    python_requires='>=3.7',
+    install_requires=[
+        "rich-argparse>=1.7.0",
+    ],
+    packages=setuptools.find_packages(),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)

xparameter/__init__.py

@@ -0,0 +1,109 @@
+from ast import literal_eval
+from rich_argparse import RichHelpFormatter
+from argparse import ArgumentParser
+from functools import partial
+
+
+class Field:
+    def __init__(self, type_, default=None, required=False, help="", freeze=False, alias=None):
+        self.type_ = type_
+        self.default = default
+        self.data = default
+        self.required = required
+        self.help = help
+        self.freeze = freeze
+        self._init_alias(alias)
+
+    def _init_alias(self, alias):
+        if alias is None:
+            self.alias = []
+        elif type(alias) == str:
+            self.alias = [alias]
+        else:
+            self.alias = alias
+    
+    def __get__(self, instance, owner):
+        return self.data
+    
+    def set_value(self, value):
+        if not isinstance(value, self.type_):
+            raise ValueError(f"Expecting {self.type_}, got {type(value)}")
+        self.data = value
+    
+    def as_args_kwargs(self):
+        args = self.alias
+        kwargs = dict(
+            default=self.default, required=self.required, help=self.help,
+        )
+        if self.type_ == bool:
+            kwargs["action"] = "store_false" if self.default else "store_true"
+        elif self.type_ in [list, tuple]:
+            kwargs["type"] = lambda value: literal_eval(value)
+            kwargs["metavar"] = self.type_.__name__
+        elif hasattr(self.type_, '_name'):
+            kwargs['type'] = lambda value: literal_eval(value)
+            kwargs['metavar'] = self.type_._name
+        else:
+            kwargs['type'] = self.type_
+            kwargs['metavar'] = self.type_.__name__
+        return args, kwargs
+    
+class Meta(type):
+    def __setattr__(cls, name, value):
+        if name in cls.__dict__:
+            attr = cls.__dict__[name]
+            if isinstance(attr, Field):
+                attr.set_value(value)
+            else:
+                super().__setattr__(name, value)
+        else:
+            raise AttributeError(f"Cannot set new attribute {name} on {cls.__class__.__name__}")
+
+class Configure(metaclass=Meta):
+
+    @classmethod
+    def as_dict(cls):
+        dict_to_return = {}
+        for attr_name, value in cls.__dict__.items():
+            if isinstance(value, Field):
+                dict_to_return[attr_name] = value.data
+            elif isinstance(value, type) and issubclass(value, Configure):
+                dict_to_return[attr_name] = value.as_dict()
+        return dict_to_return
+
+    @classmethod
+    def as_json(cls):
+        import json
+        return json.dumps(cls.as_dict(), indent=2)
+    
+    @classmethod
+    def _parse_sys_args(cls, parser: ArgumentParser):
+        parser.description = cls.__doc__
+        prefix = f"{parser.title}." if hasattr(parser, "title") else ""
+        for attr_name, value in cls.__dict__.items():
+            if isinstance(value, Field) and not value.freeze:
+                args, kwargs = value.as_args_kwargs()
+                parser.add_argument(f"--{prefix}{attr_name}", *args, **kwargs)
+            elif isinstance(value, type) and issubclass(value, Configure):
+                group = parser.add_argument_group(title=prefix + value.__name__)
+                group = value._parse_sys_args(group)
+        return parser
+    
+    @classmethod
+    def _extract_sys_args(cls, parser: ArgumentParser):
+        args = parser.parse_args()
+        for key, value in vars(args).items():
+            *namespaces, attr_name = key.split(".")
+            cls_temp = cls
+            for cls_name in namespaces:
+                cls_temp = getattr(cls_temp, cls_name)
+            cls_temp.__dict__[attr_name].set_value(value)
+
+    @classmethod
+    def parse_sys_args(cls):
+        parser = ArgumentParser(formatter_class=partial(RichHelpFormatter, max_help_position=80))
+        cls._extract_sys_args(cls._parse_sys_args(parser))
+
+    @classmethod
+    def update(cls, name, value):
+        cls.__dict__[name].set_value(value)