util Package

util Package

Utility functions, part of the Traits project.

Copyright:2003-2013 Enthought, Inc.

camel_case Module

Defines utility functions for operating on camel case names.

class traits.util.camel_case.CamelCaseToPython[source]

Simple functor class to convert names from camel case to idiomatic Python variable names.

For example::
>>> camel2python = CamelCaseToPython
>>> camel2python('XMLActor2DToSGML')

Convert a camel case string into words separated by spaces.

For example::
>>> camel_case_to_words('CamelCase')
'Camel Case'

clean_strings Module

Provides functions that mange strings to avoid characters that would be problematic in certain situations.


Munge a string to avoid characters that might be problematic as a filename in some filesystems.

traits.util.clean_strings.clean_timestamp(dt=None, microseconds=False)[source]

Return a timestamp that has been cleansed of characters that might cause problems in filenames, namely colons. If no datetime object is provided, then uses the current time.


The timestamp is in ISO-8601 format with the following exceptions:

  • Colons ‘:’ are replaced by underscores ‘_’.
  • Microseconds are not displayed if the ‘microseconds’ parameter is False.
  • dt (None or datetime.datetime) – If None, then the current time is used.
  • microseconds (bool) – Display microseconds or not.

A string timestamp.


Attempt to make a valid Python identifier out of a name.

deprecated Module

A decorator for marking methods/functions as deprecated.


A factory for decorators for marking methods/functions as deprecated.

home_directory Module


Determine the user’s home directory.

resource Module

Utility functions for managing and finding resources (ie. images/files etc).

get_path : Returns the absolute path of a class or instance

create_unique_name : Creates a name with a given prefix that is not in a
given list of existing names. The separator between the prefix and the rest of the name can also be specified (default is a ‘_’)
find_resource: Given a setuptools project specification string
(‘MyProject>=2.1’) and a partial path leading from the projects base directory to the desired resource, will return either an opened file object or, if specified, a full path to the resource.

Returns an absolute path for the specified path.

‘path’ can be a string, class or instance.

traits.util.resource.create_unique_name(prefix, names, separator='_')[source]

Creates a name starting with ‘prefix’ that is not in ‘names’.

traits.util.resource.find_resource(project, resource_path, alt_path=None, return_path=False)[source]

Returns a file object or file path pointing to the desired resource.

  • project (str) – The name of the project to look for the resource in. Can be the name or a requirement string. Ex: ‘MyProject’, ‘MyProject>1.0’, ‘MyProject==1.1’
  • resource_path (str) – The path to the file from inside the package. If the file desired is MyProject/data/image.jpg, resource_path would be ‘data/image.jpg’.
  • alt_path (str) – The path to the resource relative to the location of the application’s top-level script (the one with __main__). If this function is called in code/scripts/myscript.py and the resource is code/data/image.jpg, the alt_path would be ‘../data/image.jpg’. This path is only used if the resource cannot be found using setuptools.
  • return_path (bool) – Determines whether the function should return a file object or a full path to the resource.

file (file object or file path) – A file object containing the resource. If return_path is True, ‘file’ will be the full path to the resource. If the file is not found or cannot be opened, None is returned.


This function will find a desired resource file and return an opened file object. The main method of finding the resource uses the pkg_resources resource_stream method, which searches your working set for the installed project specified and appends the resource_path given to the project path, leading it to the file. If setuptools is not installed or it cannot find/open the resource, find_resource will use the sys.path[0] to find the resource if alt_path is defined.

traits.util.resource.store_resource(project, resource_path, filename)[source]

Store the content of a resource, given by the name of the project and the path (relative to the root of the project), into a newly created file.

The first two arguments (project and resource_path) are the same as for the function find_resource in this module. The third argument (filename) is the name of the file which will be created, or overwritten if it already exists. The return value in always None.

import_symbol Module

A function to import symbols.


Import the symbol defined by the specified symbol path.


import_symbol(‘tarfile:TarFile’) -> TarFile import_symbol(‘tarfile:TarFile.open’) -> TarFile.open

To allow compatibility with old-school traits symbol names we also allow all-dotted paths, but in this case you can only import top-level names from the module.

import_symbol(‘tarfile.TarFile’) -> TarFile

toposort Module

A simple topological sort on a dictionary graph.

exception traits.util.toposort.CyclicGraph[source]

Bases: exceptions.Exception

Exception for cyclic graphs.


Returns the nodes in the graph in topological order.

trait_documenter Module

A Trait Documenter (Subclassed from the autodoc ClassLevelDocumenter)

copyright:Copyright 2012 by Enthought, Inc
class traits.util.trait_documenter.TraitDocumenter(directive, name, indent=u'')[source]

Bases: sphinx.ext.autodoc.ClassLevelDocumenter

Specialized Documenter subclass for trait attributes.

The class defines a new documenter that recovers the trait definition signature of module level and class level traits.

To use the documenter, append the module path in the extension attribute of the conf.py.


Using the TraitDocumenter in conjunction with TraitsDoc is not advised.

objtype = 'traitattribute'
directivetype = 'attribute'
member_order = 60
priority = 12
classmethod can_document_member(member, membername, isattr, parent)[source]

Check that the documented member is a trait instance.


Trait attributes have no members

add_content(more_content, no_docstring=False)[source]

Never try to get a docstring from the trait.


Get the Trait object.


Code adapted from autodoc.Documenter.import_object.


Add the directive header ‘attribute’ with the annotation option set to the trait definition.


Add the TraitDocumenter in the current sphinx autodoc instance.