hassle.parsers API documentation

# hassle.parsers

View Source

      1import argshell
      2
      3
      4def get_edit_config_parser() -> argshell.ArgShellParser:
      5    parser = argshell.ArgShellParser(
      6        "config",
      7        description="Edit or create the `hassle_config.toml` file.",
      8    )
      9    parser.add_argument(
     10        "-n",
     11        "--name",
     12        type=str,
     13        default=None,
     14        help=" Your name. This will be used to populate the 'authors' field of a packages 'pyproject.toml'. ",
     15    )
     16    parser.add_argument(
     17        "-e",
     18        "--email",
     19        type=str,
     20        default=None,
     21        help=" Your email. This will be used to populate the 'authors' field of a packages 'pyproject.toml'. ",
     22    )
     23    parser.add_argument(
     24        "-g",
     25        "--github_username",
     26        type=str,
     27        default=None,
     28        help=""" Your github username name.
     29        When creating a new package, say with the name 'mypackage', the pyproject.toml 'Homepage' field  will be set to
     30        'https://github.com/{github_username}/mypackage'
     31        and the 'Source code' field will be set to
     32        'https://github.com/{github_username}/mypackage/tree/main/src/mypackage'.""",
     33    )
     34    parser.add_argument(
     35        "-d",
     36        "--docs_url",
     37        type=str,
     38        default=None,
     39        help=""" The template url to be used in your pyproject.toml file indicating where your project docs will be hosted.
     40        Pass the url with '$name' as a placeholder for where the package name should go,
     41        e.g. 'https://somedocswebsite/user/projects/$name'.
     42        If 'hassle_config.toml' didn't exist prior to running this tool and nothing is given for this arg, it will default to using the package's github url.
     43        e.g. for package 'mypackage' the url will be 'https://github.com/{github_username}/mypackage/tree/main/docs' """,
     44    )
     45    parser.add_argument(
     46        "-t",
     47        "--tag_prefix",
     48        type=str,
     49        default=None,
     50        help=""" When using Hassle to do `git tag`, this will be prefixed to the front of the version number in the `pyproject.toml` file.""",
     51    )
     52    return parser
     53
     54
     55def get_new_project_parser() -> argshell.ArgShellParser:
     56    parser = argshell.ArgShellParser(
     57        "new", description="Create a new project in the current directory."
     58    )
     59
     60    parser.add_argument(
     61        "name",
     62        type=str,
     63        help=""" Name of the package to create in the current working directory. """,
     64    )
     65
     66    parser.add_argument(
     67        "-s",
     68        "--source_files",
     69        nargs="*",
     70        type=str,
     71        default=[],
     72        help=""" List of additional source files to create in addition to the default
     73        __init__.py and {name}.py files.""",
     74    )
     75
     76    parser.add_argument(
     77        "-d",
     78        "--description",
     79        type=str,
     80        default="",
     81        help=""" The package description to be added to the pyproject.toml file. """,
     82    )
     83
     84    parser.add_argument(
     85        "-dp",
     86        "--dependencies",
     87        nargs="*",
     88        type=str,
     89        default=[],
     90        help=""" List of dependencies to add to pyproject.toml.
     91        Note: hassle.py will automatically scan your project for 3rd party imports and update pyproject.toml.
     92        This switch is largely useful for adding dependencies your project might need,
     93        but doesn't directly import in any source files, like an os.system() call that invokes a 3rd party cli.""",
     94    )
     95
     96    parser.add_argument(
     97        "-k",
     98        "--keywords",
     99        nargs="*",
    100        type=str,
    101        default=[],
    102        help=""" List of keywords to be added to the keywords field in pyproject.toml. """,
    103    )
    104
    105    parser.add_argument(
    106        "-as",
    107        "--add_script",
    108        action="store_true",
    109        help=""" Add section to pyproject.toml declaring the package should be installed with command line scripts added.
    110        The default is '{package_name} = "{package_name}.{package_name}:main".""",
    111    )
    112
    113    parser.add_argument(
    114        "-nl",
    115        "--no_license",
    116        action="store_true",
    117        help=""" By default, projects are created with an MIT license.
    118        Set this flag to avoid adding a license if you want to configure licensing at another time.""",
    119    )
    120
    121    parser.add_argument(
    122        "-np",
    123        "--not_package",
    124        action="store_true",
    125        help=""" Put source files in top level directory and delete tests folder. """,
    126    )
    127    return parser
    128
    129
    130def get_build_parser() -> argshell.ArgShellParser:
    131    """Returns a build parser."""
    132    parser = argshell.ArgShellParser(
    133        "build",
    134        description=""" Run the build process:
    135         * Run tests (abandoning build on failure)
    136         * Sort imports and format with Black
    137         * Update dependencies
    138         * Generate docs
    139         * Invoke `build` module""",
    140    )
    141    parser.add_argument(
    142        "-s", "--skip_tests", action="store_true", help=""" Skip running tests. """
    143    )
    144    parser.add_argument(
    145        "-o",
    146        "--overwrite_dependencies",
    147        action="store_true",
    148        help=""" Overwrite dependencies instead of appending new ones to the current contents of `pyproject.toml`. """,
    149    )
    150    parser.add_argument(
    151        "-v",
    152        "--include_versions",
    153        action="store_true",
    154        help=""" Include versions when adding dependencies. """,
    155    )
    156    return parser
    157
    158
    159def get_update_parser() -> argshell.ArgShellParser:
    160    """Returns a update parser."""
    161    parser = get_build_parser()
    162    parser.prog = "update"
    163    parser.description = """
    164    Update this package:
    165    * Run the build command (run `hassle build -h` for info)
    166    * Increment project version
    167    * Update/create changelog
    168    * git commit -m "chore: build {version}"
    169    * Git tag with new version number
    170    * Pull/push to remote
    171    """
    172    parser.add_argument(
    173        "update_type",
    174        type=str,
    175        choices=("major", "minor", "patch"),
    176        help=""" The type of update. """,
    177    )
    178    parser.add_argument(
    179        "-p",
    180        "--publish",
    181        action="store_true",
    182        help=""" Publish theupdated package to PYPI. """,
    183    )
    184    parser.add_argument(
    185        "-i",
    186        "--install",
    187        action="store_true",
    188        help=""" Install updated package. """,
    189    )
    190    return parser
    191
    192
    193def get_add_script_parser() -> argshell.ArgShellParser:
    194    """Returns a add_script parser."""
    195    parser = argshell.ArgShellParser(
    196        "add_script", description=""" Add a script to the `pyproject.toml` file. """
    197    )
    198    parser.add_argument("name", type=str, help=""" The name of the script """)
    199    parser.add_argument(
    200        "file", type=str, help=""" The file stem the function/script is located in. """
    201    )
    202    parser.add_argument(
    203        "function",
    204        nargs="?",
    205        default="main",
    206        help=""" The name of the function to invoke with the script. Defaults to `main`. """,
    207    )
    208    return parser
    209
    210
    211def add_default_source_files(args: argshell.Namespace) -> argshell.Namespace:
    212    """Add `__init__.py` and `{args.name}.py` to `args.source_files`."""
    213    args.source_files += ["__init__.py", f"{args.name}.py"]
    214    return args

def get_edit_config_parser() -> argshell.argshell.ArgShellParser: View Source

     5def get_edit_config_parser() -> argshell.ArgShellParser:
     6    parser = argshell.ArgShellParser(
     7        "config",
     8        description="Edit or create the `hassle_config.toml` file.",
     9    )
    10    parser.add_argument(
    11        "-n",
    12        "--name",
    13        type=str,
    14        default=None,
    15        help=" Your name. This will be used to populate the 'authors' field of a packages 'pyproject.toml'. ",
    16    )
    17    parser.add_argument(
    18        "-e",
    19        "--email",
    20        type=str,
    21        default=None,
    22        help=" Your email. This will be used to populate the 'authors' field of a packages 'pyproject.toml'. ",
    23    )
    24    parser.add_argument(
    25        "-g",
    26        "--github_username",
    27        type=str,
    28        default=None,
    29        help=""" Your github username name.
    30        When creating a new package, say with the name 'mypackage', the pyproject.toml 'Homepage' field  will be set to
    31        'https://github.com/{github_username}/mypackage'
    32        and the 'Source code' field will be set to
    33        'https://github.com/{github_username}/mypackage/tree/main/src/mypackage'.""",
    34    )
    35    parser.add_argument(
    36        "-d",
    37        "--docs_url",
    38        type=str,
    39        default=None,
    40        help=""" The template url to be used in your pyproject.toml file indicating where your project docs will be hosted.
    41        Pass the url with '$name' as a placeholder for where the package name should go,
    42        e.g. 'https://somedocswebsite/user/projects/$name'.
    43        If 'hassle_config.toml' didn't exist prior to running this tool and nothing is given for this arg, it will default to using the package's github url.
    44        e.g. for package 'mypackage' the url will be 'https://github.com/{github_username}/mypackage/tree/main/docs' """,
    45    )
    46    parser.add_argument(
    47        "-t",
    48        "--tag_prefix",
    49        type=str,
    50        default=None,
    51        help=""" When using Hassle to do `git tag`, this will be prefixed to the front of the version number in the `pyproject.toml` file.""",
    52    )
    53    return parser

def get_new_project_parser() -> argshell.argshell.ArgShellParser: View Source

     56def get_new_project_parser() -> argshell.ArgShellParser:
     57    parser = argshell.ArgShellParser(
     58        "new", description="Create a new project in the current directory."
     59    )
     60
     61    parser.add_argument(
     62        "name",
     63        type=str,
     64        help=""" Name of the package to create in the current working directory. """,
     65    )
     66
     67    parser.add_argument(
     68        "-s",
     69        "--source_files",
     70        nargs="*",
     71        type=str,
     72        default=[],
     73        help=""" List of additional source files to create in addition to the default
     74        __init__.py and {name}.py files.""",
     75    )
     76
     77    parser.add_argument(
     78        "-d",
     79        "--description",
     80        type=str,
     81        default="",
     82        help=""" The package description to be added to the pyproject.toml file. """,
     83    )
     84
     85    parser.add_argument(
     86        "-dp",
     87        "--dependencies",
     88        nargs="*",
     89        type=str,
     90        default=[],
     91        help=""" List of dependencies to add to pyproject.toml.
     92        Note: hassle.py will automatically scan your project for 3rd party imports and update pyproject.toml.
     93        This switch is largely useful for adding dependencies your project might need,
     94        but doesn't directly import in any source files, like an os.system() call that invokes a 3rd party cli.""",
     95    )
     96
     97    parser.add_argument(
     98        "-k",
     99        "--keywords",
    100        nargs="*",
    101        type=str,
    102        default=[],
    103        help=""" List of keywords to be added to the keywords field in pyproject.toml. """,
    104    )
    105
    106    parser.add_argument(
    107        "-as",
    108        "--add_script",
    109        action="store_true",
    110        help=""" Add section to pyproject.toml declaring the package should be installed with command line scripts added.
    111        The default is '{package_name} = "{package_name}.{package_name}:main".""",
    112    )
    113
    114    parser.add_argument(
    115        "-nl",
    116        "--no_license",
    117        action="store_true",
    118        help=""" By default, projects are created with an MIT license.
    119        Set this flag to avoid adding a license if you want to configure licensing at another time.""",
    120    )
    121
    122    parser.add_argument(
    123        "-np",
    124        "--not_package",
    125        action="store_true",
    126        help=""" Put source files in top level directory and delete tests folder. """,
    127    )
    128    return parser

def get_build_parser() -> argshell.argshell.ArgShellParser: View Source

    131def get_build_parser() -> argshell.ArgShellParser:
    132    """Returns a build parser."""
    133    parser = argshell.ArgShellParser(
    134        "build",
    135        description=""" Run the build process:
    136         * Run tests (abandoning build on failure)
    137         * Sort imports and format with Black
    138         * Update dependencies
    139         * Generate docs
    140         * Invoke `build` module""",
    141    )
    142    parser.add_argument(
    143        "-s", "--skip_tests", action="store_true", help=""" Skip running tests. """
    144    )
    145    parser.add_argument(
    146        "-o",
    147        "--overwrite_dependencies",
    148        action="store_true",
    149        help=""" Overwrite dependencies instead of appending new ones to the current contents of `pyproject.toml`. """,
    150    )
    151    parser.add_argument(
    152        "-v",
    153        "--include_versions",
    154        action="store_true",
    155        help=""" Include versions when adding dependencies. """,
    156    )
    157    return parser

Returns a build parser.

def get_update_parser() -> argshell.argshell.ArgShellParser: View Source

    160def get_update_parser() -> argshell.ArgShellParser:
    161    """Returns a update parser."""
    162    parser = get_build_parser()
    163    parser.prog = "update"
    164    parser.description = """
    165    Update this package:
    166    * Run the build command (run `hassle build -h` for info)
    167    * Increment project version
    168    * Update/create changelog
    169    * git commit -m "chore: build {version}"
    170    * Git tag with new version number
    171    * Pull/push to remote
    172    """
    173    parser.add_argument(
    174        "update_type",
    175        type=str,
    176        choices=("major", "minor", "patch"),
    177        help=""" The type of update. """,
    178    )
    179    parser.add_argument(
    180        "-p",
    181        "--publish",
    182        action="store_true",
    183        help=""" Publish theupdated package to PYPI. """,
    184    )
    185    parser.add_argument(
    186        "-i",
    187        "--install",
    188        action="store_true",
    189        help=""" Install updated package. """,
    190    )
    191    return parser

Returns a update parser.

def get_add_script_parser() -> argshell.argshell.ArgShellParser: View Source

    194def get_add_script_parser() -> argshell.ArgShellParser:
    195    """Returns a add_script parser."""
    196    parser = argshell.ArgShellParser(
    197        "add_script", description=""" Add a script to the `pyproject.toml` file. """
    198    )
    199    parser.add_argument("name", type=str, help=""" The name of the script """)
    200    parser.add_argument(
    201        "file", type=str, help=""" The file stem the function/script is located in. """
    202    )
    203    parser.add_argument(
    204        "function",
    205        nargs="?",
    206        default="main",
    207        help=""" The name of the function to invoke with the script. Defaults to `main`. """,
    208    )
    209    return parser

Returns a add_script parser.

def add_default_source_files(args: argshell.argshell.Namespace) -> argshell.argshell.Namespace: View Source

    212def add_default_source_files(args: argshell.Namespace) -> argshell.Namespace:
    213    """Add `__init__.py` and `{args.name}.py` to `args.source_files`."""
    214    args.source_files += ["__init__.py", f"{args.name}.py"]
    215    return args

Add `__init__.py` and `{args.name}.py` to `args.source_files`.