



namespaces 4.2.0 documentation

namespaces[¶](#namespaces "Permalink to this headline")

=======================================================

> 

> Namespaces are one honking great idea – let’s do more of those!

> 

> 

> —[PEP 20: The Zen of Python](https://www.python.org/dev/peps/pep-0020/)

> 

> 

> 

Namespaces are:

* Pythonic structs

* Python dict with dot-notation access

* Javascript-like objects for Python

Basic Usage[¶](#basic-usage "Permalink to this headline")

---------------------------------------------------------

```

import namespaces as ns

ab = ns.Namespace(a=1, b=2)

frozen\_ab = ns.FrozenNamespace(ab)

frozen\_ab.b # => 2

ab.c # => AttributeError

ab.c = 3

ab.c # => 3

frozen\_ab.c = 3 # => AttributeError

```

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

```

$ pip install namespaces

```

Navigation[¶](#navigation "Permalink to this headline")

-------------------------------------------------------

### Design[¶](#design "Permalink to this headline")

The goal of namespaces is to improve code readability by leveraging

*beautiful* dot-notation instead of relying on `str` when describing

object attributes.

namespaces was born out of a desire for a mutable `namedtuple`.

#### Before & after[¶](#before-after "Permalink to this headline")

Before:

```

joey = {'name': 'joey', 'height': 70, 'age': 24}

joey['species'] = 'kangaroo'

print(joey['name'], 'is a', joey['species'])

```

After:

```

import namespaces as ns

joey = ns.Namespace(name='joey', height=70, age=24)

joey.species = 'kangaroo'

print(joey.name, 'is a', joey.species)

```

#### namespaces vs dict[¶](#namespaces-vs-dict "Permalink to this headline")

Namespaces is **not** meant as a replacement for dict.

Use a namespace if:

* you will be accessing items individually by name

* you can enumerate and name items as you write your code

* you want the semantics of a Javascript object

* you want a dynamic, mutable `namedtuple`

Use a `dict` if:

* you will be accessing items in batches programmatically

* you *cannot* enumerate or name items as you write your code

* you need keys that are not `str`

### namespaces API[¶](#namespaces-api "Permalink to this headline")

#### Namespace[¶](#namespace "Permalink to this headline")

*class* `namespaces.``Namespace`(*\*args*, *\*\*kwargs*)[¶](#namespaces.Namespace "Permalink to this definition")

Pythonic structs | Python dict with dot-notation access |

Javascript-like objects for Python.

Creation is equivalent to creating a `dict` with the positional

arguments args and keyword arguments kwargs. In other words, if it works

for the `dict` constructor, it will work for the `Namespace`

constructor.

| Parameters: | * **args** – Items as positional arguments.

* **kwargs** – Items as keyword arguments.

 |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1, b=2, c=3)

>>> foo

Namespace(a=1, b=2, c=3)

>>> bar = ns.Namespace({'a': 1, 'b': 2, 'c': 3})

>>> bar

Namespace(a=1, b=2, c=3)

>>> baz = ns.Namespace()

>>> baz.a = 1

>>> baz.a

1

>>> baz['a']

1

>>> baz.a is baz['a']

True

>>> baz['b'] = 2

>>> baz['b']

2

>>> baz.b

2

>>> baz['b'] is baz.b

True

```

`__delitem__`(*name*)[¶](#namespaces.Namespace.__delitem__ "Permalink to this definition")

Delete item via bracket-notation.

| Parameters: | **name** (*str*) – Key |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1)

>>> del foo['a'] # calls foo.\_\_delitem\_\_('a')

>>> foo

Namespace()

```

`__getattr__`(*name*)[¶](#namespaces.Namespace.__getattr__ "Permalink to this definition")

Look up item via dot-notation.

| Parameters: | **name** (*str*) – Key |

| Returns: | Associated value |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1)

>>> foo.a # calls foo.\_\_getattr\_\_('a')

1

>>> foo.b

AttributeError: 'Namespace' object has no attribute 'b'

```

`__getitem__`(*name*)[¶](#namespaces.Namespace.__getitem__ "Permalink to this definition")

Get item via bracket-notation.

| Parameters: | **name** (*str*) – Key |

| Returns: | Associated value |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1)

>>> foo['a'] # calls foo.\_\_getitem\_\_('a')

1

```

`__iter__`()[¶](#namespaces.Namespace.__iter__ "Permalink to this definition")

Iterator over item keys.

| Returns: | Key iterator |

| Return type: | collections.KeysView |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1, b=2, c=3)

>>> for key in foo: # calls foo.\_\_iter\_\_()

>>>   print(key)

a

b

c

```

`__len__`()[¶](#namespaces.Namespace.__len__ "Permalink to this definition")

Calculates length of this Namespace.

| Returns: | Length of this Namespace |

| Return type: | int |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace(a=1, b=2, c=3)

>>> len(foo)

3

```

`__setattr__`(*name*, *value*)[¶](#namespaces.Namespace.__setattr__ "Permalink to this definition")

Set item via dot-notation.

| Parameters: | * **name** (*str*) – Key

* **value** – New associated value

 |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace()

>>> foo.a = 1 # calls foo.\_\_setattr\_\_('a', 1)

>>> foo

Namespace(a=1)

```

`__setitem__`(*name*, *value*)[¶](#namespaces.Namespace.__setitem__ "Permalink to this definition")

Set item via bracket-notation.

| Parameters: | * **name** (*str*) – Key

* **value** – New associated value

 |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.Namespace()

>>> foo['a'] = 1 # calls foo.\_\_setitem\_\_('a', 1)

>>> foo

Namespace(a=1)

```

#### FrozenNamespace[¶](#frozennamespace "Permalink to this headline")

*class* `namespaces.``FrozenNamespace`(*\*args*, *\*\*kwargs*)[¶](#namespaces.FrozenNamespace "Permalink to this definition")

Immutable, hashable dictionary whose items are also available via dot-notation.

`__getattr__`(*name*)[¶](#namespaces.FrozenNamespace.__getattr__ "Permalink to this definition")

Look up item via dot-notation.

| Parameters: | **name** (*str*) – Key |

| Returns: | Associated value |

Usage::

```

>>> import namespaces as ns

>>> foo = ns.FrozenNamespace(a=1)

>>> foo.a # calls foo.\_\_getattr\_\_('a')

1

>>> foo.b

AttributeError: 'Namespace' object has no attribute 'b'

```

`__getitem__`(*name*)[¶](#namespaces.FrozenNamespace.__getitem__ "Permalink to this definition")

Get item via bracket-notation.

| Parameters: | **name** (*str*) – Key |

| Returns: | Corresponding value |

Usage::

```

>>> import namespaces as ns

>>> foo = ns.FrozenNamespace(a=1)

>>> foo['a'] # calls foo.\_\_getitem\_\_('a')

1

```

`__hash__`()[¶](#namespaces.FrozenNamespace.__hash__ "Permalink to this definition")

Caches lazily-evaluated hash for performance.

| Returns: | Hash value for this FrozenNamespace |

| Return type: | int |

Usage::

```

>>> import namespaces as ns

>>> foo = ns.FrozenNamespace(a=1)

>>> hash(foo) # calls foo.\_\_hash\_\_()

-2550060783245333914

```

`__iter__`()[¶](#namespaces.FrozenNamespace.__iter__ "Permalink to this definition")

Iterator over item keys.

| Returns: | Key iterator |

| Return type: | collections.KeysView |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.FrozenNamespace(a=1, b=2, c=3)

>>> for key in foo: # calls foo.\_\_iter\_\_()

...     print(key)

a

b

c

```

`__len__`()[¶](#namespaces.FrozenNamespace.__len__ "Permalink to this definition")

Calculates length of this FrozenNamespace

| Returns: | Length of this FrozenNamespace |

| Return type: | int |

Usage:

```

>>> import namespaces as ns

>>> foo = ns.FrozenNamespace(a=1, b=2, c=3)

>>> len(foo) # calls foo.\_\_len\_\_()

3

```

#### utils[¶](#module-namespaces.utils "Permalink to this headline")

*class* `namespaces.utils.``NamespaceEncoder`(*skipkeys=False*, *ensure\_ascii=True*, *check\_circular=True*, *allow\_nan=True*, *sort\_keys=False*, *indent=None*, *separators=None*, *encoding='utf-8'*, *default=None*)[¶](#namespaces.utils.NamespaceEncoder "Permalink to this definition")

Custom JSON encoder that converts both FrozenNamespace and Namespace to a dict.

#### Reserved keys[¶](#reserved-keys "Permalink to this headline")

`Namespace` reserves the key `\_dict`.

`FrozenNamespace` reserves the keys `\_dict` and `\_hash`.

In general, any and all reserved keys will be prefixed with an `\_`.

Warning

If you override the values for the reserved keys, all bets are off.

### Support[¶](#support "Permalink to this headline")

If you are in need of assistance, please leave an issue on the namespaces

github repository: <https://github.com/pcattori/namespaces/issues>

### Contribute[¶](#contribute "Permalink to this headline")

Pull requests welcome!

The namespaces github repository can be found [here](https://github.com/pcattori/namespaces).

It is recommended that you follow the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) when contributing.

#### Tests[¶](#tests "Permalink to this headline")

* pass current tests python setup.py test

* codecov

* python 2/3 compatibility

	+ caniusepython3

	+ pylint –py3k

	+ travis w/ py2.7 and py3.5

### License[¶](#license "Permalink to this headline")

The MIT License (MIT)

Copyright (c) 2016 Pedro Cattori

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the “Software”), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

[![Logo](_static/kangaroo.png)](index.html#document-index)

### [Table Of Contents](index.html#document-index)

* [Design](index.html#document-design)

	+ [Before & after](index.html#before-after)

	+ [namespaces vs dict](index.html#namespaces-vs-dict)

* [namespaces API](index.html#document-api)

	+ [Namespace](index.html#namespace)

	+ [FrozenNamespace](index.html#frozennamespace)

	+ [utils](index.html#module-namespaces.utils)

	+ [Reserved keys](index.html#reserved-keys)

* [Support](index.html#document-support)

* [Contribute](index.html#document-contribute)

	+ [Tests](index.html#tests)

* [License](index.html#document-license)

### Related Topics

* [Documentation overview](index.html#document-index)

### Quick search

 Enter search terms or a module, class or function name.

 

 ©2016, Pedro Cattori.

 

 |

 Powered by [Sphinx 1.3.5](http://sphinx-doc.org/)

 & [Alabaster 0.7.9](https://github.com/bitprophet/alabaster)

