con24ma 1.1.0__py3-none-any.whl

con24ma/__init__.py

@@ -0,0 +1 @@
+from .dscls import *

con24ma/action.py

@@ -0,0 +1,19 @@
+import ast, argparse
+
+
+def opt_action(key: str):
+    if key == 'parse_kwargs': return ParseKwargs
+    return key
+
+
+class ParseKwargs(argparse.Action):
+
+    def __call__(self, parser, namespace, values: list[str], *args, **kwargs):
+        kw = {}
+        for value in values:
+            key, value = value.split('=')
+            try:
+                kw[key] = ast.literal_eval(value)
+            except ValueError:
+                kw[key] = str(value)
+        setattr(namespace, self.dest, kw)

con24ma/dscls/__init__.py

@@ -0,0 +1,2 @@
+from .config import *
+from .field import *

con24ma/dscls/config.py

@@ -0,0 +1,93 @@
+import argparse
+from typing import Optional, Self
+from dataclasses import asdict, dataclass, fields
+
+from .field import ArgField, DictField
+
+
+@dataclass
+class BaseConfig:
+    """Dataclass-based config base providing safe instantiation and dict conversion."""
+
+    @classmethod
+    def safe_build(cls,
+                   return_unused_kwargs: bool = True,
+                   **kwargs) -> tuple[Self, dict] | Self:
+        """Build an instance using only kwargs that match declared fields.
+
+        Args:
+            return_unused_kwargs: If True, also return kwargs not consumed by this class.
+            **kwargs: Configuration values; unrecognised keys are left untouched.
+
+        Returns:
+            A (instance, unused_kwargs) tuple when return_unused_kwargs is True,
+            otherwise the instance alone.
+        """
+        safe_kwargs = {}
+        for _f in fields(cls):
+            n = _f.name
+            if n in kwargs: safe_kwargs[n] = kwargs.pop(n)
+        if return_unused_kwargs: return cls(**safe_kwargs), kwargs
+        return cls(**safe_kwargs)
+
+    def asdict(self) -> dict:
+        """Return all fields as a plain dictionary."""
+        return asdict(self)
+
+
+@dataclass
+class DataClassConfig(BaseConfig):
+    """Config class with argparse-based CLI argument parsing.
+
+    Fields annotated with ArgField or DictField are automatically registered
+    as command-line arguments on the parser.
+    """
+
+    @staticmethod
+    def get_parsercls(**kwargs):
+        """Return an ArgumentParser instance. Override in subclasses to swap the parser type."""
+        return argparse.ArgumentParser(**kwargs)
+
+    @classmethod
+    def get_parser(cls) -> argparse.ArgumentParser:
+        """Build and return an ArgumentParser from fields declared as ArgField or DictField."""
+        parser = cls.get_parsercls()
+        for _f in fields(cls):
+            if not isinstance(_f.default, (ArgField, DictField)):
+                continue
+            af = _f.default
+            dest = ['--' + _f.name.replace('_', '-')]
+            if af.dest is not None:
+                dest += [af.dest] if isinstance(af.dest, str) else af.dest
+            parser.add_argument(*dest, **af.get_argument(_f.type))
+        return parser
+
+    @classmethod
+    def prep_parsed(cls, parsed: dict) -> dict:
+        """Pre-process the raw parsed dict before instantiation. Override to transform values."""
+        return parsed
+
+    @classmethod
+    def parse_args(cls, inputs: Optional[list[str]] = None,
+                   base_dict: dict = {}):
+        """Parse command-line arguments and return a config instance with any remaining args.
+
+        Args:
+            inputs: Argument list to parse; defaults to sys.argv when None.
+            base_dict: Base dictionary to merge parsed values into.
+
+        Returns:
+            A (config instance, remaining unparsed args) tuple.
+        """
+        parser = cls.get_parser()
+        parsed, remain = parser.parse_known_args(inputs)
+        parsed = cls.prep_parsed(vars(parsed))
+        base_dict.update(parsed)
+        for _f in fields(cls):
+            default = _f.default_factory
+            if not hasattr(default, 'parse_args'): continue
+            if _f.name in base_dict:
+                base_dict.update(**base_dict.pop(_f.name))
+            base_dict[_f.name], remain = default.parse_args(remain, base_dict)
+        temp = {k.name: base_dict.pop(k.name, k.default) for k in fields(cls)}
+        return cls(**temp), remain

con24ma/dscls/field.py

@@ -0,0 +1,62 @@
+from typing import Optional, Sequence, Type, Union
+
+from con24ma.action import opt_action
+from con24ma.pathutil import getpath
+
+
+def argument_of_AP(action: Optional[str] = None,
+                   nargs: Optional[int|str] = None,
+                   const = None, 
+                   choices: Optional[Sequence] = None,
+                   required: Optional[bool] = None,
+                   help: Optional[str] = None,
+                   metavar: Optional[str] = None):
+    kw = dict()
+    if action is not None: kw['action'] = opt_action(action)
+    if nargs is not None: kw['nargs'] = nargs
+    if const is not None: kw['const'] = const
+    return kw
+
+
+class ArgField:
+
+    def __init__(self, value, 
+                 dest: Optional[Union[list[str]|str]] = None, **kwargs):
+        self.value = value
+        self.dest = dest
+
+        self.args_add_argument = argument_of_AP(**kwargs)
+    
+    def __bool__(self): return bool(self.value)
+
+    def __float__(self): return float(self.value)
+    
+    def __int__(self): return int(self.value)
+
+    def __str__(self): return str(self.value)
+
+    def get_argument(self, value_type: Type) -> dict:
+        kw = self.args_add_argument
+        if kw.get('action', '') == '':
+            kw['type'] = value_type
+            kw['default'] = self.value
+        return kw
+
+
+class DictField(ArgField):
+
+    def __init__(self, value: dict = {}, 
+                 dest: Optional[Union[list[str]|str]] = None, **kwargs):
+        super().__init__(value, dest=dest, 
+                         action='parse_kwargs', nargs = '*', **kwargs)
+
+
+def _set_value(default = None, default_factory = None, **kwargs):
+    if default is not None: return default, kwargs
+    if default_factory is not None: return default_factory, kwargs
+    return None, kwargs
+
+
+def argfield(**kwargs) -> ArgField:
+    value, kwargs = _set_value(**kwargs)
+    return ArgField(value, **kwargs)

con24ma/pathutil.py

@@ -0,0 +1,17 @@
+import re, pathlib
+from typing import Optional, Union
+
+def _root(init: Optional[str] = None):
+    if init is None: return pathlib.Path()
+    if init == '/': return pathlib.Path('/')
+    if init == '~/': return pathlib.Path.home()
+
+def joindir(path: pathlib.Path, join: str, mkdir: bool = False) -> pathlib.Path:
+    path = path.joinpath(join)
+    path.mkdir(parents=True, exist_ok=mkdir)
+    return path
+
+def getpath(path: Union[pathlib.Path|str], mkdir: bool = False) -> pathlib.Path:
+    if isinstance(path, pathlib.Path): return path
+    init, path = re.match(r"(~?/)?(.*)", path).groups()
+    return joindir(_root(init), path, mkdir=mkdir)

con24ma-1.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: con24ma
+Version: 1.1.0
+Summary: Configuration tools
+Author-email: Linqa Kiriyama <kyamlinqa@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://example.com
+Project-URL: Documentation, https://con24ma.readthedocs.io/
+Project-URL: Repository, https://github.com/qnilix/con24ma.git
+Project-URL: Bug Tracker, https://github.com/qnilix/con24ma/issues
+Project-URL: Changelog, https://github.com/qnilix/con24ma/blob/master/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CONfiguration tools for MAnaging your environment (con24ma)
+
+A practical Python package for creating command-line interfaces from dataclasses with powerful argument parsing capabilities.
+
+## Installation
+
+```bash
+pip install ./con24ma
+```
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from dataclasses import dataclass
+from con24ma import DataClassConfig, ArgField, DictField
+
+@dataclass
+class Config(DataClassConfig):
+    name: str = ArgField('myapp', help="Application name")
+    debug: bool = ArgField(False, help="Enable debug mode")
+    config: dict = DictField(help="Additional configuration")
+
+# Parse and use
+config, remaining_args = Config.parse_args()
+print(f"Running {config.name} with debug={config.debug}")
+```
+
+### Command Line Usage
+
+```bash
+python script.py --name MyApp --debug --config timeout=30 retries=3
+# Output: Running MyApp with debug=True
+# config.config = {'timeout': 30, 'retries': 3}
+```
+
+## Real-World Example
+
+```python
+from dataclasses import dataclass
+from typing import Optional
+from con24ma import DataClassConfig, ArgField, DictField
+
+@dataclass
+class ModelConfig(DataClassConfig):
+    # Core model settings
+    model: str = ArgField('resnet50', ['-m'], help="Model architecture name")
+    model_kwargs: dict = DictField(help="Additional model parameters as key=value")
+
+    # Training settings
+    pretrained: Optional[bool] = ArgField(None, help="Use pretrained weights")
+    trained_file: Optional[str] = ArgField(None, help="Path to trained model file")
+
+# Usage
+config, _ = ModelConfig.parse_args()
+```
+
+```bash
+python train.py -m efficientnet_b0 --pretrained --model-kwargs drop_rate=0.2 num_classes=1000
+```
+
+## Key Features
+
+- **Type-safe**: Full dataclass type support with automatic CLI generation
+- **DictField**: Built-in support for `key=value` argument parsing
+- **Flexible**: Custom argument destinations, choices, validation
+- **Serializable**: Easy JSON configuration save/load
+- **Extensible**: Hook methods for custom processing
+
+## Documentation
+
+For detailed documentation and advanced usage examples:
+
+- **[Field Types Guide](docs/FIELDS.md)** - Complete reference for ArgField, DictField, and other field types
+- **[Argument Parsing Details](docs/ARG_PARSE.md)** - Deep dive into the kwargs parsing system and advanced argument handling
+
+## Basic API
+
+### DataClassConfig
+
+Main base class for configuration dataclasses.
+
+```python
+@dataclass
+class Config(DataClassConfig):
+    # Define fields with ArgField/DictField
+    pass
+
+# Parse arguments
+config, remaining = Config.parse_args()
+```
+
+### ArgField
+
+Standard command-line argument field.
+
+```python
+# Basic usage
+name: str = ArgField("default", help="Help text")
+
+# With custom options
+verbose: bool = ArgField(False, ['-v', '--verbose'], help="Verbose mode")
+mode: str = ArgField("train", choices=['train', 'test'], help="Mode")
+```
+
+### DictField
+
+Dictionary field for key=value parsing.
+
+```python
+# Parse --config key1=value1 key2=value2
+config: dict = DictField(help="Configuration parameters")
+```
+
+## Best Practices
+
+### Configuration Validation
+
+```python
+@dataclass
+class Config(DataClassConfig):
+    learning_rate: float = ArgField(0.001, help="Learning rate")
+    
+    @classmethod
+    def prep_parsed(cls, parsed: dict) -> dict:
+        if parsed.get('learning_rate', 0) <= 0:
+            raise ValueError("Learning rate must be positive")
+        return parsed
+```
+
+### Configuration Persistence
+
+```python
+import json
+
+# Save configuration
+config, _ = Config.parse_args()
+with open('config.json', 'w') as f:
+    json.dump(config.asdict(), f, indent=2)
+
+# Load and merge with CLI args
+with open('config.json', 'r') as f:
+    saved_config = json.load(f)
+config, _ = Config.parse_args(base_dict=saved_config)
+```
+
+## Requirements
+
+- Python 3.9+
+- Standard library only (no external dependencies)
+
+## License
+
+This project is released under MIT License.

con24ma-1.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+con24ma/__init__.py,sha256=WyjLZFtg6bZ-lVoQg_qsU8i8KA-QZWatnk0b3EiXo40,20
+con24ma/action.py,sha256=AIJxQWMgxxmtoplbAUK6lgaPBm8B003OImO5BOS8wcQ,494
+con24ma/pathutil.py,sha256=YtP1WWtvhWdbDRQ6a6VLL51UfPm2RDW0oeJagCuzUNI,643
+con24ma/dscls/__init__.py,sha256=KTKRnzVo3-b0q1NPAtmGOePz0oR0V9upKXOX3eiekE8,42
+con24ma/dscls/config.py,sha256=AjHsSf84ZDAQLjTqT3D2hg2oR7oBqm4lK5lCNnKh_Qw,3472
+con24ma/dscls/field.py,sha256=NoBe_GjIv_fnj69fGC7wwNRP5tauzsNiMclKAL6rEbI,1897
+con24ma-1.1.0.dist-info/licenses/LICENSE,sha256=ZCxi6HhjbSDje3K6cmjq0wn-Fd9zJ7drDk5oN622oRM,1062
+con24ma-1.1.0.dist-info/METADATA,sha256=r2K_7dZaWsCPGqd1lFlI9fN1HwDFLJlg1PALWCpOiFU,4556
+con24ma-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+con24ma-1.1.0.dist-info/entry_points.txt,sha256=-8kofrHVj9YazPbTMIYzlPY-IjdVDAlBf30tq36RYNc,41
+con24ma-1.1.0.dist-info/top_level.txt,sha256=KpY-yChCFFG2vtJWscCcQwfDBGxC8rU1-1JWvioBCfg,8
+con24ma-1.1.0.dist-info/RECORD,,

con24ma-1.1.0.dist-info/WHEEL

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

con24ma-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pandapp = con24ma:main

con24ma-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 qaiLN
+
+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.

con24ma-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+con24ma