namedspace Module — namedspace 1.0.1 documentation

### Navigation

- index
- modules |
- previous |
- namedspace 1.0.1 documentation »

# namedspace Module

`namedspace.` `namedspace`(typename, required_fields=(), optional_fields=(), mutable_fields=(), default_values=<frozendict {}>, default_value_factories=<frozendict {}>)

  Builds a new class that encapsulates a namespace and provides various ways to access it.

  The typename argument is required and is the name of the namedspace class that will be generated.

  The required_fields and optional_fields arguments can be a string or sequence of strings and together specify the fields that instances of the namedspace class have.

  Values for the required fields must be provided somehow when the instance is created. Values for optional fields may be provided later, or maybe not at all.

  The mutable_fields argument specifies which fields will be mutable, if any. By default, all fields are immutable and all instances are hashable and can be used as dictionary keys. If any fields are set as mutable, all instances are not hashable and cannot be used as dictionary keys.

  The default_values mapping provides simple default values for the fields.

  The default_value_factories mapping provides a more flexible, but more complex, mechanism for providing default values. The value of each item is a callable that takes a single argument, the namedspace instance, and returns the default value for the field.

  The default_values_factories mapping is only consulted if there is no default value for the field in the default_values mapping.

  Here is a simple example, using only the required fields argument:

      >>> SimpleNS = namedspace("SimpleNS", ("id", "name", "description"))

      >>> SimpleNS
      <class 'namedspace.SimpleNS'>

  Once the class has been created, it can be instantiated like any other class. However, a value for all of the required fields must be provided.

      >>> simple_ns = SimpleNS(id=1, description="Simple Description")
      Traceback (most recent call last):
          <snip/>
      ValueError: A value for field 'name' is required.

      >>> simple_ns = SimpleNS(id=1, name="Simple Name", description="Simple Description")

      >>> simple_ns
      SimpleNS(id=1, name='Simple Name', description='Simple Description')

  An instance of a namedspace class provides standard attribute access to its fields.

      >>> simple_ns.id
      1

      >>> simple_ns.name
      'Simple Name'

      >>> simple_ns.description
      'Simple Description'

  In addition to standard attribute access, instances of a namedspace class implement a MutableMapping interface.

      >>> 'id' in simple_ns
      True

      >>> for field_name in simple_ns:
      ...     print field_name
      id
      name
      description

      >>> len(simple_ns)
      3

      >>> simple_ns["id"]
      1

      >>> simple_ns["name"]
      'Simple Name'

      >>> simple_ns["description"]
      'Simple Description'

  There are built-in properties to access collections and iterators associated with the namespace.

  The namespace encapsulated by a namedspace class is stored in an OrderedDict, so order of the collections is the same as the order that the fields were specified.

  All of these properties use the standard “protected” naming convention in order to not pollute the public namespace.

      >>> simple_ns._field_names
      ('id', 'name', 'description')

      >>> tuple(simple_ns._field_names_iter)
      ('id', 'name', 'description')

      >>> simple_ns._field_values
      (1, 'Simple Name', 'Simple Description')

      >>> tuple(simple_ns._field_values_iter)
      (1, 'Simple Name', 'Simple Description')

      >>> simple_ns._field_items
      [('id', 1), ('name', 'Simple Name'), ('description', 'Simple Description')]

      >>> list(simple_ns._field_items_iter)
      [('id', 1), ('name', 'Simple Name'), ('description', 'Simple Description')]

      >>> simple_ns._as_dict
      OrderedDict([('id', 1), ('name', 'Simple Name'), ('description', 'Simple Description')])

  Here is a more complex example, using all of the arguments:

      >>> from itertools import count

      >>> ComplexNS = namedspace("ComplexNS", "id", optional_fields=("name", "description", "extra"),
      ...     mutable_fields=("description", "extra"), default_values={"description": "None available"},
      ...     default_value_factories={"id": lambda self, counter=count(start=1): counter.next(),
      ...         "name": lambda self: "Name for id={id}".format(id=self.id)})

      >>> complex_ns1 = ComplexNS()

      >>> complex_ns1.id
      1

  The value of 1 was automatically assigned by the default_value_factory for the ‘id’ field, in this case a lambda closure that hooks up an instance of itertools.count.

      >>> complex_ns1.name
      'Name for id=1'

  This value was also generated by a default value factory. In this case, the factory for the ‘name’ attribute uses the value of the ‘id’ attribute to compute the default value.

      >>> complex_ns1.description
      'None available'

  This value came from the default_values mapping.

  The description field was set as a mutable field, which allows it to be modified.

      >>> complex_ns1.description = "Some fancy description"
      >>> complex_ns1.description
      'Some fancy description'

  Its value can also be deleted.

      >>> del complex_ns1.description
      >>> complex_ns1.description
      'None available'

  Since its modified value was deleted, and it has a default value, it has reverted to its default value.

  The extra field is a valid field in this namedspace, but it has not yet been assigned a value and does not have a default.

      >>> complex_ns1.extra
      Traceback (most recent call last):
          <snip/>
      AttributeError: "Field 'extra' does not yet exist in this ComplexNS namedspace instance."

  Since it one of the mutable fields, we can give it a value.

      >>> complex_ns1.extra = "Lasts a long, long time"
      >>> complex_ns1.extra
      'Lasts a long, long time'

  Only fields that have been declared as either required or optional are allowed.

      >>> complex_ns1.some_other_field = "some other value"
      Traceback (most recent call last):
          <snip/>
      FieldNameError: "Field 'some_other_field' does not exist in ComplexNS namedspace."

  Finally, to illustrate that our counter is working as it should, if we instantiate another instance, our id field will get the next counter value.

      >>> complex_ns2 = ComplexNS()
      >>> complex_ns2.id
      2

### Navigation

- index
- modules |
- previous |
- namedspace 1.0.1 documentation »