# i2.base

Tools to provide meta-interfaces (“mints”) of python objects.

A mint is a `Mapping` view of the (meta-)information describing the interface of
an object: for a callable, its parameters (name, kind, default, annotation) and its
return annotation.

Main entry points:

- `Mint`: mint of any python object
- `MintOfCallable`: mint of a callable, with parameter information
- `ParametersMint`: mint of the parameters of a callable

### Functions

| [`is_not_empty`](#i2.base.is_not_empty)(obj)   | False for `inspect.Parameter.empty` and `NotFoundType` instances, True otherwise.   |
|----------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| [`name_of_obj`](#i2.base.name_of_obj)(o)      | Deprecated alias of `i2.signatures.name_of_obj` (emits a `DeprecationWarning`).     |

### Classes

| [`AttrFromKey`](#i2.base.AttrFromKey)(d)                   | Expose the keys of a mapping as attributes (`obj.k` reads `d[k]`).                         |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| [`KeyFromAttr`](#i2.base.KeyFromAttr)(d)                   | Expose the attributes of an object as mapping keys (`obj[k]` reads `getattr(d, k)`).       |
| [`Mint`](#i2.base.Mint)(obj[, attrs])               | Get a Mint object of a python object.                                                      |
| [`MintOfCallable`](#i2.base.MintOfCallable)(obj[, attrs])     | Get a Mint object of a python object.                                                      |
| [`MintOfCallableMixin`](#i2.base.MintOfCallableMixin)()            | Mint attributes computed from a callable's signature (parameters, return annotation, doc). |
| [`MintOfDocMixin`](#i2.base.MintOfDocMixin)()                 | Placeholder mixin for parsed-docstring mint attributes (not implemented yet).              |
| [`NotFoundType`](#i2.base.NotFoundType)()                   | Type of the `not_found` sentinel: falsy, repr `NotFound`.                                  |
| [`ParameterMint`](#i2.base.ParameterMint)(param[, position]) | Mint of one parameter: its name, kind, default and annotation (and position, if given).    |
| [`ParametersMint`](#i2.base.ParametersMint)([params])         | Get mint of the parameters of a callable.                                                  |

### *class* i2.base.AttrFromKey(d)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Expose the keys of a mapping as attributes (`obj.k` reads `d[k]`).

### *class* i2.base.KeyFromAttr(d)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Expose the attributes of an object as mapping keys (`obj[k]` reads `getattr(d, k)`).

### *class* i2.base.Mint(obj, attrs=None)

Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)

Get a Mint object of a python object.
A Mint will provide parameters that provide (meta-)information about the interface of the python object.

```pycon
>>> from pprint import pprint
>>> # Mint of a function
>>> def f(my_arg: int = 7) -> int:
...     return my_arg + 10
>>> mint = Mint(f)
>>> mint.obj_name, mint.type_name, mint.module_name, mint.obj_name
('f', 'function', 'i2.base', 'f')
>>> # Mint of a module
>>> import os as myos
>>> mint = Mint(myos)
>>> mint.obj_name, mint.type_name, mint.module_name, mint.obj_name
('os', 'module', 'os', 'os')
>>> assert set(list(mint)) == {'module_name', 'module', 'type_name', 'obj_name'}
>>> # Mint of a variable
>>> v = 10
>>> mint = Mint(v)
>>> mint.obj_name, mint.type_name, mint.module_name, mint.obj_name
(NotFound, 'int', NotFound, NotFound)
>>> assert set(list(mint)) == {'type_name'}  # see that there's only one non-null attr!
```

#### items() → a set-like object providing a view on D's items

### *class* i2.base.MintOfCallable(obj, attrs=None)

Bases: [`Mint`](#i2.base.Mint), [`MintOfCallableMixin`](#i2.base.MintOfCallableMixin), [`MintOfDocMixin`](#i2.base.MintOfDocMixin)

Get a Mint object of a python object.
A Mint will provide parameters that provide (meta-)information about the interface of the python object.

```pycon
>>> from pprint import pprint
>>> def f(my_arg: int = 7) -> int:
...     return my_arg + 10
>>> f.__doc__ = 'some documentation'
>>>
>>> mint = MintOfCallable(f)
>>> mint.obj_name
'f'
>>> mint.type_name
'function'
>>> mint.module_name
'i2.base'
>>> mint.parameters.my_arg
{'name': 'my_arg', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 7, 'annotation': <class 'int'>, 'position': 0}
>>> mint.doc_string
'some documentation'
>>> mint.return_annotation
<class 'int'>
>>> def g(a, b: 'some_string_id_of_a_custom_type', c=1, d: int = 1) -> float:
...     return a * b * c * d
>>> pprint(dict(MintOfCallable(g).parameters))
{'a': {'name': 'a', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0},
 'b': {'name': 'b', 'kind': 'POSITIONAL_OR_KEYWORD', 'annotation': 'some_string_id_of_a_custom_type', 'position': 1},
 'c': {'name': 'c', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'position': 2},
 'd': {'name': 'd', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'annotation': <class 'int'>, 'position': 3}}
```

### *class* i2.base.MintOfCallableMixin

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Mint attributes computed from a callable’s signature (parameters, return annotation, doc).

### *class* i2.base.MintOfDocMixin

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Placeholder mixin for parsed-docstring mint attributes (not implemented yet).

### *class* i2.base.NotFoundType

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Type of the `not_found` sentinel: falsy, repr `NotFound`.

### *class* i2.base.ParameterMint(param, position=None)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Mint of one parameter: its name, kind, default and annotation (and position, if given).

Accepts an `inspect.Parameter`-like object or a mapping with those keys; missing
attributes are set to `inspect.Parameter.empty`.

### *class* i2.base.ParametersMint(params={})

Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)

Get mint of the parameters of a callable.

```pycon
>>> import inspect
>>> from pprint import pprint
>>>
>>> def g(a, b: 'some_type', c=1, d: int = 1) -> float:
...     return a * b * c * d
>>> mint = ParametersMint(inspect.signature(g).parameters)
>>> # mint is a mapping (like a read-only dict), so...
>>> list(mint)
['a', 'b', 'c', 'd']
>>>
>>> for arg_spec in mint.values():
...     print(arg_spec)
{'name': 'a', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0}
{'name': 'b', 'kind': 'POSITIONAL_OR_KEYWORD', 'annotation': 'some_type', 'position': 1}
{'name': 'c', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'position': 2}
{'name': 'd', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'annotation': <class 'int'>, 'position': 3}
>>> t = list(mint.items())
>>> t[0]
('a', {'name': 'a', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0})
>>> t[1]
('b', {'name': 'b', 'kind': 'POSITIONAL_OR_KEYWORD', 'annotation': 'some_type', 'position': 1})
>>>
>>> mint = ParametersMint(inspect.signature(g).parameters)
>>> pprint(dict(mint))
{'a': {'name': 'a', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0},
 'b': {'name': 'b', 'kind': 'POSITIONAL_OR_KEYWORD', 'annotation': 'some_type', 'position': 1},
 'c': {'name': 'c', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'position': 2},
 'd': {'name': 'd', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': 1, 'annotation': <class 'int'>, 'position': 3}}
```

```pycon
>>> # and now, some cannibalistic fun...
>>> # The following is skipped because not working in 3.10
>>> pprint(
...     dict(ParametersMint(inspect.signature(ParametersMint).parameters))
... )
{'args': {'name': 'args', 'kind': 'VAR_POSITIONAL', 'position': 0},
 'kwds': {'name': 'kwds', 'kind': 'VAR_KEYWORD', 'position': 1}}
>>> pprint(
...     dict(ParametersMint(inspect.signature(ParametersMint.__init__).parameters))
... )
{'params': {'name': 'params', 'kind': 'POSITIONAL_OR_KEYWORD', 'default': FrozenDict({}), 'position': 1},
 'self': {'name': 'self', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0}}
>>> pprint(
...     dict(ParametersMint(inspect.signature(ParametersMint.__new__).parameters))
... )
{'args': {'name': 'args', 'kind': 'VAR_POSITIONAL', 'position': 1},
 'cls': {'name': 'cls', 'kind': 'POSITIONAL_OR_KEYWORD', 'position': 0},
 'kwds': {'name': 'kwds', 'kind': 'VAR_KEYWORD', 'position': 2}}
```

#### items() → a set-like object providing a view on D's items

### i2.base.is_not_empty(obj)

False for `inspect.Parameter.empty` and `NotFoundType` instances, True otherwise.

### i2.base.name_of_obj(o)

Deprecated alias of `i2.signatures.name_of_obj` (emits a `DeprecationWarning`).