# API reference

While Snimpy is targeted at being used interactively or through simple scripts, you can also use it from your Python program.

It provides a high-level interface as well as lower-level ones. However, the effort is only put in th `manager` module and other modules are considered as internal details.

## `manager` module

## Internal modules

Those modules shouldn’t be used directly.

### `mib` module

This module is a low-level interface to manipulate and extract information from MIB files. It is a CFFI wrapper around libsmi. You may find convenient to use it in other projects but the wrapper is merely here to serve Snimpy use and is therefore incomplete.

class snimpy.mib.Column(node)

  MIB column node. This class represent a column of a table.

  property table

    Get table associated with this column.

    Returns:

      The `Table` instance associated to this column.

class snimpy.mib.Node(node)

  MIB node. An instance of this class represents a MIB node. It can be specialized by other classes, like `Scalar`, `Table`, `Column`, `Node`.

  property enum

    Get possible enum values. When the node can only take a discrete number of values, those values are defined in the MIB and can be retrieved through this property.

    Returns:

      The dictionary of possible values keyed by the integer value.

  property fmt

    Get node format. The node format is a string to use to display a user-friendly version of the node. This is can be used for both octet strings or integers (to make them appear as decimal numbers).

    Returns:

      The node format as a string or None if there is no format available.

  property oid

    Get OID for the current node. The OID can then be used to request the node from an SNMP agent.

    Returns:

      OID as a tuple

  property ranges

    Get node ranges. An node can be restricted by a set of ranges. For example, an integer can only be provided between two values. For strings, the restriction is on the length of the string.

    The returned value can be None if no restriction on range exists for the current node, a single value if the range is fixed or a list of tuples or fixed values otherwise.

    Returns:

      The valid range for this node.

  property type

    Get the basic type associated with this node.

    Returns:

      The class from `basictypes` module which can represent the node. When retrieving a valid value for this node, the returned class can be instanciated to get an appropriate representation.

  property typeName

    Retrieves the name of the the node’s current declared type (not basic type).

    Returns:

      A string representing the current declared type, suitable for assignment to type.setter.

class snimpy.mib.Notification(node)

  MIB notification node. This class represent a notification.

  property objects

    Get objects for a notification.

    Returns:

      The list of objects (as `Column`, `Node` or `Scalar` instances) of the notification.

exception snimpy.mib.SMIException

  SMI related exception. Any exception thrown in this module is inherited from this one.

class snimpy.mib.Scalar(node)

  MIB scalar node. This class represents a scalar value in the MIB. A scalar value is a value not contained in a table.

class snimpy.mib.Table(node)

  MIB table node. This class represents a table. A table is an ordered collection of objects consisting of zero or more rows. Each object in the table is identified using an index. An index can be a single value or a list of values.

  property columns

    Get table columns. The columns are the different kind of objects that can be retrieved in a table.

    Returns:

      list of table columns (`Column` instances)

  property implied

    Is the last index implied? An implied index is an index whose size is not fixed but who is not prefixed by its size because this is the last index of a table.

    Returns:

      True if and only if the last index is implied.

  property index

    Get indexes for a table. The indexes are used to locate a precise row in a table. They are a subset of the table columns.

    Returns:

      The list of indexes (as `Column` instances) of the table.

snimpy.mib.get(mib, name)

  Get a node by its name.

  Parameters:

    - mib – The MIB name to query

    - name – The object name to get from the MIB

  Returns:

    the requested MIB node (`Node`)

snimpy.mib.getByOid(oid)

  Get a node by its OID.

  Parameters:

    oid – The OID as a tuple

  Returns:

    The requested MIB node (`Node`)

snimpy.mib.getColumns(mib)

  Return all columns from a givem MIB.

  Parameters:

    mib – The MIB name

  Returns:

    The list of all columns for the MIB

  Return type:

    list of `Column` instances

snimpy.mib.getNodes(mib)

  Return all nodes from a given MIB.

  Parameters:

    mib – The MIB name

  Returns:

    The list of all MIB nodes for the MIB

  Return type:

    list of `Node` instances

snimpy.mib.getNotifications(mib)

  Return all notifications from a givem MIB.

  Parameters:

    mib – The MIB name

  Returns:

    The list of all notifications for the MIB

  Return type:

    list of `Notification` instances

snimpy.mib.getScalars(mib)

  Return all scalars from a given MIB.

  Parameters:

    mib – The MIB name

  Returns:

    The list of all scalars for the MIB

  Return type:

    list of `Scalar` instances

snimpy.mib.getTables(mib)

  Return all tables from a given MIB.

  Parameters:

    mib – The MIB name

  Returns:

    The list of all tables for the MIB

  Return type:

    list of `Table` instances

snimpy.mib.load(mib)

  Load a MIB into the library.

  Parameters:

    mib – The MIB to load, either a filename or a MIB name.

  Returns:

    The MIB name that has been loaded.

  Raises:

    SMIException – The requested MIB cannot be loaded.

snimpy.mib.loadedMibNames()

  Generates the list of loaded MIB names.

  Yield:

    The names of all currently loaded MIBs.

snimpy.mib.path(path=None)

  Set or get a search path to libsmi.

  When no path is provided, return the current path, unmodified. Otherwise, set the path to the specified value.

  Parameters:

    path – The string to be used to change the search path or None

snimpy.mib.reset()

  Reset libsmi to its initial state.

### `snmp` module

### `basictypes` module

This module is aimed at providing Pythonic representation of various SNMP types. Each SMIv2 type is mapped to a corresponding class which tries to mimic a basic type from Python. For example, display strings are like Python string while SMIv2 integers are just like Python integers. This module is some kind of a hack and its use outside of Snimpy seems convoluted.

class snimpy.basictypes.Bits(entity, value, raw=True)

  Class for bits.

  pack()

    Prepare the instance to be sent on the wire.

class snimpy.basictypes.Boolean(entity, value, raw=True)

  Class for a boolean.

class snimpy.basictypes.Enum(entity, value, raw=True)

  Class for an enumeration. An enumaration is an integer but labels are attached to some values for a more user-friendly display.

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

class snimpy.basictypes.Integer(entity, value, raw=True)

  Class for any integer.

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.IpAddress(entity, value, raw=True)

  Class representing an IP address/

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.OctetString(entity, value, raw=True)

  Class for a generic octet string. This class should be compared to `String` which is used to represent a display string. This class is usually used to store raw bytes, like a bitmask of VLANs.

class snimpy.basictypes.Oid(entity, value, raw=True)

  Class to represent and OID.

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.String(entity, value, raw=True)

  Class for a display string. Such a string is an unicode string and it is therefore expected that only printable characters are used. This is usually the case if the corresponding MIB node comes with a format string.

  With such an instance, the user is expected to be able to provide a formatted. For example, a MAC address could be written 00:11:22:33:44:55.

class snimpy.basictypes.StringOrOctetString(entity, value, raw=True)
  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.Timeticks(entity, value, raw=True)

  Class for timeticks.

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.Type(entity, value, raw=True)

  Base class for all types.

  classmethod fromOid(entity, oid, implied=False)

    Create instance from an OID.

    This is the sister function of `toOid()`.

    Parameters:

      - oid – The OID to use to create an instance

      - entity – The MIB entity we want to instantiate

    Returns:

      A couple (l, v) with l the number of suboids needed to create the instance and v the instance created from the OID

  pack()

    Prepare the instance to be sent on the wire.

  toOid(implied=False)

    Convert to an OID.

    If this function is implemented, then class function `fromOid()` should also be implemented as the “invert” function of this one.

    This function only works if the entity is used as an index! Otherwise, it should raises NotImplementedError.

    Returns:

      An OID that can be used as index

class snimpy.basictypes.Unsigned32(entity, value, raw=True)

  Class to represent an unsigned 32bits integer.

  pack()

    Prepare the instance to be sent on the wire.

class snimpy.basictypes.Unsigned64(entity, value, raw=True)

  Class to represent an unsigned 64bits integer.

  pack()

    Prepare the instance to be sent on the wire.

snimpy.basictypes.build(mibname, node, value)

  Build a new basic type with the given value.

  Parameters:

    - mibname – The MIB to use to locate the entity.

    - node – The node that will be attached to this type.

    - value – The initial value to set for the type.

  Returns:

    A `Type` instance