Python: Typehints for argparse.Namespace objects

Consider defining an extension class to argparse.Namespace that provides the type hints you want:

class MyProgramArgs(argparse.Namespace):
    def __init__():
        self.somearg = 'defaultval' # type: str

Then use namespace= to pass that to parse_args:

def process_argv():
    parser = argparse.ArgumentParser()
    parser.add_argument('--somearg')
    nsp = MyProgramArgs()
    parsed = parser.parse_args(['--somearg','someval'], namespace=nsp)  # type: MyProgramArgs
    the_arg = parsed.somearg  # <- Pycharm should not complain

Most of these answers involve using another package to handle the typing. This would be a good idea only if there wasn't such a simple solution as the one I am about to propose.

Step 1. Type Declarations

First, define the types of each argument in a dataclass like so:

from dataclasses import dataclass

@dataclass
class MyProgramArgs:
    first_var: str
    second_var: int

Step 2. Argument Declarations

Then you can set up your parser however you like with matching arguments. For example:

import argparse

parser = argparse.ArgumentParser("This CLI program uses type hints!")
parser.add_argument("-a", "--first-var")
parser.add_argument("-b", "--another-var", type=int, dest="second_var")

Step 3. Parsing the Arguments

And finally, we parse the arguments in a way that the static type checker will know about the type of each argument:

my_args = MyProgramArgs(**vars(parser.parse_args())

Now the type checker knows that my_args is of type MyProgramArgs so it knows exactly which fields are available and what their type is.

I don't know anything about how PyCharm handles these typehints, but understand the Namespace code.

argparse.Namespace is a simple class; essentially an object with a few methods that make it easier to view the attributes. And for ease of unittesting it has a __eq__ method. You can read the definition in the argparse.py file.

The parser interacts with the namespace in the most general way possible - with getattr, setattr, hasattr. So you can use almost any dest string, even ones you can't access with the .dest syntax.

Make sure you don't confuse the add_argument type= parameter; that's a function.

Using your own namespace class (from scratch or subclassed) as suggested in the other answer may be the best option. This is described briefly in the documentation. Namespace Object. I haven't seen this done much, though I've suggested it a few times to handle special storage needs. So you'll have to experiment.

If using subparsers, using a custom Namespace class may break, http://bugs.python.org/issue27859

Pay attention to handling of defaults. The default default for most argparse actions is None. It is handy to use this after parsing to do something special if the user did not provide this option.

 if args.foo is None:
     # user did not use this optional
     args.foo = 'some post parsing default'
 else:
     # user provided value
     pass

That could get in the way type hints. Whatever solution you try, pay attention to the defaults.

A namedtuple won't work as a Namespace.

First, the proper use of a custom Namespace class is:

nm = MyClass(<default values>)
args = parser.parse_args(namespace=nm)

That is, you initial an instance of that class, and pass it as the parameter. The returned args will be the same instance, with new attributes set by parsing.

Second, a namedtuple can only created, it can't be changed.

In [72]: MagicSpace=namedtuple('MagicSpace',['foo','bar'])
In [73]: nm = MagicSpace(1,2)
In [74]: nm
Out[74]: MagicSpace(foo=1, bar=2)
In [75]: nm.foo='one'
...
AttributeError: can't set attribute
In [76]: getattr(nm, 'foo')
Out[76]: 1
In [77]: setattr(nm, 'foo', 'one')    # not even with setattr
...
AttributeError: can't set attribute

A namespace has to work with getattr and setattr.

Another problem with namedtuple is that it doesn't set any kind of type information. It just defines field/attribute names. So there's nothing for the static typing to check.

While it is easy to get expected attribute names from the parser, you can't get any expected types.

For a simple parser:

In [82]: parser.print_usage()
usage: ipython3 [-h] [-foo FOO] bar
In [83]: [a.dest for a in parser._actions[1:]]
Out[83]: ['foo', 'bar']
In [84]: [a.type for a in parser._actions[1:]]
Out[84]: [None, None]

The Actions dest is the normal attribute name. But type is not the expected static type of that attribute. It is a function that may or may not convert the input string. Here None means the input string is saved as is.

Because static typing and argparse require different information, there isn't an easy way to generate one from the other.

I think the best you can do is create your own database of parameters, probably in a dictionary, and create both the Namespace class and the parsesr from that, with your own utility function(s).

Let's say dd is dictionary with the necessary keys. Then we can create an argument with:

parser.add_argument(dd['short'],dd['long'], dest=dd['dest'], type=dd['typefun'], default=dd['default'], help=dd['help'])

You or someone else will have to come up with a Namespace class definition that sets the default (easy), and static type (hard?) from such a dictionary.

If you are in a situation where you can start from scratch there are interesting solutions like

• the already mentioned typed argument parser (TAP)
• typer
• typed-args

However, in my case they weren't an ideal solution because:

1. I have many existing CLIs based on argparse, and I cannot afford to re-write them all using such args-inferred-from-types approaches.
2. When inferring args from types it can be tricky to support all advanced CLI features that plain argparse supports.
3. Re-using common arg definitions in multiple CLIs is often easier in plain imperative argparse compared to alternatives.

Therefore I worked on a tiny library typed_argparse that allows to introduce typed args without much refactoring. The idea is to add a type derived from a special TypedArg class, which then simply wraps the plain argparse.Namespace object:

# Step 1: Add an argument type.
class MyArgs(TypedArgs):
    foo: str
    num: Optional[int]
    files: List[str]


def parse_args(args: List[str] = sys.argv[1:]) -> MyArgs:
    parser = argparse.ArgumentParser()
    parser.add_argument("--foo", type=str, required=True)
    parser.add_argument("--num", type=int)
    parser.add_argument("--files", type=str, nargs="*")
    # Step 2: Wrap the plain argparser result with your type.
    return MyArgs(parser.parse_args(args))


def main() -> None:
    args = parse_args(["--foo", "foo", "--num", "42", "--files", "a", "b", "c"])
    # Step 3: Done, enjoy IDE auto-completion and strong type safety
    assert args.foo == "foo"
    assert args.num == 42
    assert args.files == ["a", "b", "c"]

This approach slightly violates the single-source-of-truth principle, but the library performs a full runtime validation to ensure that the type annotations match the argparse types, and it is just a very simple option to migrate towards typed CLIs.

Here's Jason Leaver's solution with amos's suggested improvement:

import argparse

class Namespace(argparse.Namespace):
    name: str

parser = argparse.ArgumentParser()
parser.add_argument("--name")

args = parser.parse_args(namespace=Namespace())

Another way to do it which could be ideal if you have few arguments is as follows.

First make a function that sets up the parser and returns the namespace. For example:

def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument("-a")
    parser.add_argument("-b", type=int)
    return parser.parse_args()

Then you define a main function which takes the args you declared above individually; like so.

def main(a: str, b: int):
    print("hello world", a, b)

And when you call your main, you do it like this:

if __name__ == "__main__":
    main(**vars(parse_args())

From your main onwards, you'll have your variables a and b properly recognised by your static type checker, although you won't have an object any more containing all your arguments, which may be a good or bad thing depending on your use case.

TL;DR: Namespace isn't necessary, use the class as a type annotation. Works with passing through functions/methods as well. Supported all the way down to python3.5

class MyProgramArgs(argparse.Namespace):
    my_arg1: str
    my_arg2: dict[str, str]

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--my_arg1')
    parser.add_argument('--my_arg2')

    parsed: MyProgramArgs = parser.parse_args()

    the_arg1: str = parsed.my_arg1             # <- Pycharm should not complain
    the_arg2: dict[str, str] = parsed.my_arg2  # <- Pycharm should not complain
    the_arg3: str = parsed.my_arg2             # <- Pycharm SHOULD complain

Details: As I was unable to respond to @aghast's answer, I want to provide the simplest solution to this that I was able to arrive at after working through this for a couple weeks.

Using the namespace isn't necessary in his implementation (per the docs) as it's designed to be used to assign attributes to an existing object, nsp in his case, which aghast didn't use in his solution, e.g.

# bad, not using instantiated MyProgramArgs() object
nsp = MyProgramArgs()
parsed = parser.parse_args(['--somearg','someval'], namespace=nsp)
the_arg = parsed.somearg  # <- Pycharm should not complain

# using namespace properly
nsp = MyProgramArgs()
parser.parse_args(['--somearg','someval'], namespace=nsp)  # note no assignment
the_arg = nsp.somearg  # Properly accessing assigned attributes from provided namespace object

Either:

1. Don't instantiate nsp as it's unused, use the class as the type annotation for the variable(s), and skip namespace entirely, e.g. parsed: MyProgramArgs = parser.parse_args().
2. Use namespace properly per the docs and my example above.

Using custom argparse.Namespace + dataclass.Field.metadata + trivial transform of metadata to add_arguments() calls:

import sys, os, dataclasses as dc, argparse as ap

@dc.dataclass
class Args(ap.Namespace):
    work_dir: str = dc.field(default=os.getcwd(),
                             metadata={"name_or_flags": ["-p", "--path"],
                                       "metavar": "PATH",
                                       "help": "working dir",
                                       "dest": "work_dir"})
    output: str = dc.field(default="./output.txt",
                           metadata={"name_or_flags": ["-o", "--output"],
                                     "metavar": "FILE",
                                     "help": "output file name"})

def parse_args(arg_parser, namespace) -> Args:
    #  Transform metadata to add_argument() calls
    for field in dc.fields(namespace):
        kwargs = field.metadata.copy()
        args = kwargs.pop("name_or_flags")
        arg_parser.add_argument(*args, **kwargs)
    #  Parse command line
    return arg_parser.parse_args(namespace=namespace)

def main():
    args = parse_args(ap.ArgumentParser(), Args())
    print(f"working_dir: {args.work_dir}")
    print(f"output: {args.output}")
    return 0

if __name__ == "__main__":
    sys.exit(main())

PyCharm hints:

Output:

# test.py -h 
usage: test.py [-h] [-p PATH] [-o FILE]

options:
  -h, --help            show this help message and exit
  -p PATH, --path PATH  working dir
  -o FILE, --output FILE
                        output file name

# test.py -p ../test 
working_dir: ../test
output: ./output.txt

a super solution to just type hint the NameSpace return value of parse_args method.

import argparse
from typing import Type


class NameSpace(argparse.Namespace, Type):
    name: str


class CustomParser(argparse.ArgumentParser):
    def parse_args(self) -> NameSpace:
        return super().parse_args()


parser = CustomParser()

parser.add_argument("--name")

if __name__ == "__main__":
    args = parser.parse_args()
    print(args.name)

Easy solution if you don't need your parsed args class to inherit from Namespace:

@dataclass
class MyTypedArgs:
    input_path: str
    output_path: str
    verbose: bool

def parse_args():
    parser = argparse.ArgumentParser(description="Does stuff, very useful")
    
    # ... add some args

    args = parser.parse_args()
    return cast(MyTypedArgs, args)

You can get fancier than this by implementing some of the Namespace class by hand if you end up needing to (or cast back to Namespace).