Programmatic API reference
==========================

This page describes parts of inmanta code base that provide a stable API that could be used from modules or extensions.

.. warning::
    Only those parts explicitly mentioned here are part of the API. They provide a stable
    interface. Other parts of the containing modules provide no such guarantees.


Constants
---------

.. autoclass:: inmanta.const.LogLevel
    :show-inheritance:
    :members:
    :undoc-members:
.. autoclass:: inmanta.const.ResourceAction
    :show-inheritance:
    :members:
    :undoc-members:


.. _compiler-exceptions:

Compiler exceptions
-------------------

.. autoclass:: inmanta.ast.CompilerException
    :show-inheritance:

.. autoclass:: inmanta.parser.ParserException
    :show-inheritance:

.. autoclass:: inmanta.ast.RuntimeException
    :show-inheritance:

.. autoclass:: inmanta.ast.ExternalException
    :show-inheritance:

.. autoclass:: inmanta.ast.ExplicitPluginException
    :show-inheritance:

Plugins
-------

.. autoclass:: inmanta.plugins.Context
    :members:
    :undoc-members:

.. autofunction:: inmanta.plugins.plugin

.. autoclass:: inmanta.plugins.PluginException

Resources
---------

.. autofunction:: inmanta.resources.resource
.. autoclass:: inmanta.resources.Resource
    :members: clone

.. autoclass:: inmanta.resources.PurgeableResource
.. autoclass:: inmanta.resources.ManagedResource
.. autoclass:: inmanta.resources.IgnoreResourceException
.. autoclass:: inmanta.resources.Id
    :members: parse_id, resource_str
    :undoc-members:

.. autoclass:: inmanta.execute.util.Unknown

Handlers
--------

.. autofunction:: inmanta.agent.handler.cache
.. autofunction:: inmanta.agent.handler.provider
.. autoclass:: inmanta.agent.handler.SkipResource
    :show-inheritance:
    :members:
.. autoclass:: inmanta.agent.handler.ResourcePurged
    :members:
.. autoclass:: inmanta.agent.handler.HandlerContext
    :members:
.. autoclass:: inmanta.agent.handler.ResourceHandler
    :members:
    :undoc-members:
    :private-members:

.. autoclass:: inmanta.agent.handler.CRUDHandler
    :members:
    :inherited-members:
    :undoc-members:
.. autoclass:: inmanta.agent.io.local.LocalIO
    :members:
    :inherited-members:
    :undoc-members:


Export
------

.. autodecorator:: inmanta.export.dependency_manager


Attributes
----------

.. autoclass:: inmanta.ast.attribute.Attribute
    :members: validate, get_type, type
    :undoc-members:

.. autoclass:: inmanta.ast.attribute.RelationAttribute
    :show-inheritance:


Modules
-------

.. autoclass:: inmanta.module.InstallMode
    :members:
    :undoc-members:
    :show-inheritance:

.. autodata:: inmanta.module.INSTALL_OPTS

.. autoclass:: inmanta.module.InvalidModuleException

.. autoclass:: inmanta.module.InvalidMetadata

.. autoclass:: inmanta.module.ModuleLike
    :members: metadata, name
    :undoc-members:

.. autoclass:: inmanta.module.Module
    :show-inheritance:


Project
-------

.. autoclass:: inmanta.module.Project
    :members: get, load, set
    :undoc-members:
    :show-inheritance:


Typing
------

The `inmanta.ast.type` module contains a representation of inmanta types, as well as validation logic for
those types.

.. autoclass:: inmanta.ast.type.Type
    :members: validate, type_string, is_primitive, get_base_type, with_base_type
    :undoc-members:

.. autoclass:: inmanta.ast.type.NullableType
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Primitive
    :members: cast
    :undoc-members:
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Number
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Integer
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Bool
    :show-inheritance:

.. autoclass:: inmanta.ast.type.String
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Union
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Literal
    :show-inheritance:

.. autoclass:: inmanta.ast.type.List
    :show-inheritance:

.. autoclass:: inmanta.ast.type.TypedList
    :show-inheritance:

.. autoclass:: inmanta.ast.type.LiteralList
    :show-inheritance:

.. autoclass:: inmanta.ast.type.Dict
    :show-inheritance:

.. autoclass:: inmanta.ast.type.TypedDict
    :show-inheritance:

.. autoclass:: inmanta.ast.type.LiteralDict
    :show-inheritance:

.. autoclass:: inmanta.ast.type.ConstraintType
    :show-inheritance:

.. autodata:: inmanta.ast.type.TYPES
    :annotation:

.. note::
    The type classes themselves do not represent inmanta types, their instances do. For example, the
    type representation for the inmanta type `number` is `Number()`, not `Number`.


Protocol
--------

.. autoclass:: inmanta.protocol.common.Result
    :members: code, result
    :undoc-members:


Data
----

.. warning::
    In contrast to the rest of this section, the data API interface is subject to change. It is documented here because it is
    currently the only available API to interact with the data framework. A restructure of the data framework is expected at
    some point. Until then, this API should be considered unstable.

.. data:: inmanta.data.TBaseDocument
    :annotation: : typing.TypeVar

    TypeVar with BaseDocument bound.

.. autoclass:: inmanta.data.BaseDocument
    :members: get_by_id, get_list
    :undoc-members:

.. autoclass:: inmanta.data.Compile
    :members: get_substitute_by_id, to_dto
    :undoc-members:
    :show-inheritance:

.. autoclass:: inmanta.data.ConfigurationModel
    :members: get_versions
    :undoc-members:
    :show-inheritance:

.. autoclass:: inmanta.data.Environment
    :show-inheritance:

.. autoclass:: inmanta.data.Report
    :show-inheritance:

.. autoclass:: inmanta.data.Resource
    :members: get_resources_for_version
    :undoc-members:
    :show-inheritance:

.. autoclass:: inmanta.data.ResourceAction
    :members: get_logs_for_version
    :undoc-members:
    :show-inheritance:

.. autoclass:: inmanta.data.model.BaseModel
    :show-inheritance:

    .. autoclass:: inmanta.data.model::BaseModel.Config
        :members:
        :undoc-members:

.. autodata:: inmanta.data.model.ResourceIdStr

.. autodata:: inmanta.data.model.ResourceVersionIdStr


Domain conversion
-----------------

This section describes methods for converting values between the plugin domain and the internal domain.
This conversion is performed automatically for plugin arguments and return values so it is only required
when bypassing the usual plugin workflow by calling internal methods directly.

.. autoclass:: inmanta.execute.proxy.DynamicProxy()
    :members: return_value, unwrap
    :undoc-members:

Rest API
---------

The rest API is also available as a `swagger spec <openapi.html#http://>`_

.. automodule:: inmanta.protocol.methods
    :members:

.. automodule:: inmanta.protocol.methods_v2
    :members:
