{"id":13737794,"url":"https://github.com/linkedin/smart-arg","last_synced_at":"2025-08-17T01:34:53.661Z","repository":{"id":43171165,"uuid":"279728865","full_name":"linkedin/smart-arg","owner":"linkedin","description":"Smart Arguments Suite (smart-arg) is a slim and handy python lib that helps one work safely and conveniently with command line arguments.","archived":false,"fork":false,"pushed_at":"2021-12-16T06:39:52.000Z","size":498,"stargazers_count":23,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-29T07:33:59.015Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linkedin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-15T01:11:17.000Z","updated_at":"2024-01-19T10:27:30.000Z","dependencies_parsed_at":"2022-09-06T12:00:23.877Z","dependency_job_id":null,"html_url":"https://github.com/linkedin/smart-arg","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/linkedin/smart-arg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2Fsmart-arg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2Fsmart-arg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2Fsmart-arg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2Fsmart-arg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkedin","download_url":"https://codeload.github.com/linkedin/smart-arg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkedin%2Fsmart-arg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270796216,"owners_count":24647319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:02:01.244Z","updated_at":"2025-08-17T01:34:53.620Z","avatar_url":"https://github.com/linkedin.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Smart Argument Suite (`smart-arg`)\n\n[![GitHub tag](https://img.shields.io/github/tag/linkedin/smart-arg.svg)](https://GitHub.com/linkedin/smart-arg/tags/)\n[![PyPI version](https://img.shields.io/pypi/v/smart-arg.svg)](https://pypi.python.org/pypi/smart-arg/)\n\nSmart Argument Suite (`smart-arg`) is a slim and handy Python library that helps one work safely and conveniently \nwith the arguments that are represented by an immutable argument container class' fields \n([`NamedTuple`](https://docs.python.org/3.7/library/typing.html?highlight=namedtuple#typing.NamedTuple) or \n[`dataclass`](https://docs.python.org/3.7/library/dataclasses.html#dataclasses.dataclass) out-of-box),\nand passed through command-line interfaces.\n\n`smart-arg` promotes arguments type-safety, enables IDEs' code autocompletion and type hints \nfunctionalities, and helps one produce correct code.\n\n![](smart-arg-demo.gif)\n\n## Quick start\n\nThe [`smart-arg`](https://pypi.org/project/smart-arg/) package is available through `pip`.\n```shell\npip3 install smart-arg\n```\n\nUsers can bring or define, if not already, their argument container class -- a `NamedTuple` or `dataclass`,\nand then annotate it with `smart-arg` decorator `@arg_suite` in their Python scripts.\n\nNow an argument container class instance, e.g. `my_arg` of `MyArg` class, once created, is ready to be serialized by the `smart-arg` API --\n`my_arg.__to_argv__()` to a sequence of strings, passed through the command-line interface \nand then deserialized back to an instance again by `my_arg = MyArg.__from_argv__(sys.argv[1:])`.\n\n```python\nimport sys\nfrom typing import NamedTuple, List, Tuple, Dict, Optional\nfrom smart_arg import arg_suite\n\n\n# Define the argument container class\n@arg_suite\nclass MyArg(NamedTuple):\n    \"\"\"\n    MyArg is smart! (docstring goes to description)\n    \"\"\"\n    nn: List[int]  # Comments go to argparse help\n    a_tuple: Tuple[str, int]  # a random tuple argument\n    encoder: str  # Text encoder type\n    h_param: Dict[str, int]  # Hyperparameters\n    batch_size: Optional[int] = None\n    adp: bool = True  # bool is a bit tricky\n    embedding_dim: int = 100  # Size of embedding vector\n    lr: float = 1e-3  # Learning rate\n\n\ndef cli_interfaced_job_scheduler():\n    \"\"\"\n    This is to be called by the job scheduler to set up the job launching command,\n    i.e., producer side of the Python job arguments\n    \"\"\"\n    # Create the argument container instance\n    my_arg = MyArg(nn=[3], a_tuple=(\"str\", 1), encoder='lstm', h_param={}, adp=False)  # The patched argument container class requires keyword arguments to instantiate the class\n\n    # Serialize the argument to command-line representation\n    argv = my_arg.__to_argv__()\n    cli = 'my_job.py ' + ' '.join(argv)\n    # Schedule the job with command line `cli`\n    print(f\"Executing job:\\n{cli}\")\n    # Executing job:\n    # my_job.py --nn 3 --a_tuple str 1 --encoder lstm --h_param --batch_size None --adp False --embedding_dim 100 --lr 0.001\n\n\ndef my_job(my_arg: MyArg):\n    \"\"\"\n    This is the actual job defined by the input argument my_arg,\n    i.e., consumer side of the Python job arguments\n    \"\"\"\n    print(my_arg)\n    # MyArg(nn=[3], a_tuple=('str', 1), encoder='lstm', h_param={}, batch_size=None, adp=False, embedding_dim=100, lr=0.001)\n    \n    # `my_arg` can be used in later script with a typed manner, which help of IDEs (type hints and auto completion)\n    # ...\n    print(f\"My network has {len(my_arg.nn)} layers with sizes of {my_arg.nn}.\")\n    # My network has 1 layers with sizes of [3].\n\n\n# my_job.py\nif __name__ == '__main__':\n    # Deserialize the command-line representation of the argument back to a container instance \n    arg_deserialized: MyArg = MyArg.__from_argv__(sys.argv[1:])  # Equivalent to `MyArg(None)`, one positional arg required to indicate the arg is a command-line representation.\n    my_job(arg_deserialized)\n```\n\n```shell-session\n\u003e python my_job.py -h\nusage: my_job.py [-h] --nn [int [int ...]] --a_tuple str int --encoder str\n                 --h_param [str:int [str:int ...]] [--batch_size int]\n                 [--adp {True,False}] [--embedding_dim int] [--lr float]\n\nMyArg is smart! (docstring goes to description)\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --nn [int [int ...]]  (List[int], required) Comments go to argparse help\n  --a_tuple str int     (Tuple[str, int], required) a random tuple argument\n  --encoder str         (str, required) Text encoder type\n  --h_param [str:int [str:int ...]]\n                        (Dict[str, int], required) Hyperparameters\n  --batch_size int      (Optional[int], default: None)\n  --adp {True,False}    (bool, default: True) bool is a bit tricky\n  --embedding_dim int   (int, default: 100) Size of embedding vector\n  --lr float            (float, default: 0.001) Learning rate\n\n```\n## Promoted practices\n* Focus on defining the arguments diligently, and let the `smart-arg` \n  (backed by [argparse.ArgumentParser](https://docs.python.org/3/library/argparse.html#argumentparser-objects)) \n  work its magic around command-line interface. \n* Always work directly with argument container class instances when possible, even if you only need to generate the command-line representation.\n* Stick to the default behavior and the basic features, think twice before using any of the [advanced features](https://smart-arg.readthedocs.io/en/latest/advanced.html#advanced-usages).\n\n\n## More detail\nFor more features and implementation detail, please refer to the [documentation](https://smart-arg.readthedocs.io/).\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## License\n\nThis project is licensed under the BSD 2-CLAUSE LICENSE - see the [LICENSE.md](LICENSE.md) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkedin%2Fsmart-arg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkedin%2Fsmart-arg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkedin%2Fsmart-arg/lists"}