comma package

Submodules

comma.abstract module

class comma.abstract.CloneableCollection

Bases: object

An abstract collection (containing a data attribute, for instance, from collections.UserList or collections.UserDict) that can be cloned with new data.

clone(newdata=None, no_parent=False, **kwargs)

Returns a clone of the current collection, with possible different underlying data, as specified by newdata.

Parameters

newdata (Any) –

comma.config module

comma.exceptions module

exception comma.exceptions.CommaBatchException

Bases: comma.exceptions.CommaException

A batch update was not possible, because invalid.

exception comma.exceptions.CommaException

Bases: Exception

The base exception for the comma package.

exception comma.exceptions.CommaInvalidHeaderException

Bases: comma.exceptions.CommaException, TypeError

The value for a header is not of the right type: It appears not to be a list/iterable of strings (column names).

exception comma.exceptions.CommaKeyError

Bases: comma.exceptions.CommaException, KeyError

The requested key is not part of the header of this file.

exception comma.exceptions.CommaNoHeaderException

Bases: comma.exceptions.CommaException, KeyError

A header was expected (or necessary to an operation) but was not found.

exception comma.exceptions.CommaOrphanException

Bases: comma.exceptions.CommaException

An internal reference has been broken.

exception comma.exceptions.CommaOrphanRowException

Bases: comma.exceptions.CommaOrphanException

A row required access to information from its parent CSV file but was unable to.

exception comma.exceptions.CommaOrphanTableException

Bases: comma.exceptions.CommaOrphanException

A table required access to information from its parent CSV file but was unable to.

exception comma.exceptions.CommaTypeError

Bases: comma.exceptions.CommaException, TypeError

The type error for the comma package.

comma.extras module

comma.extras.detect_csv_type(sample, delimiters=None)

Returns a dictionary containing meta-data on a CSV file, such as the format “dialect”, whether the file is likely to have a header and the kind of line terminator that has been detected. This version of the helper method is based on the excellent/essential Python package clevercsv by Gertjan van den Burg (@GjjvdBurg), see https://github.com/alan-turing-institute/CleverCSV.

Parameters

  • sample (AnyStr) –

  • delimiters (Optional[Iterable]) –

comma.extras.detect_encoding(sample, default='utf-8')

Detects the encoding of a sample string, using the following heuristics in this sequential order:

1. Check to see if we can find a BOM (Byte Order Mark) that may suggest one variant of Unicode as an encoding. The BOMs are defined in the codecs standard module.

2. If unsuccessful, and if chardet is available, use chardet to statistically determine the most likely encoding based on the composition of the sample (the longer the sample, the more reliable this method).

3. If unsuccessful, return the value of the default parameter; this will be “utf-8” if unchanged.

Parameters

  • sample (AnyStr) –

  • default (Optional[str]) –

Return type

Optional[str]

comma.extras.is_binary_string(bytestring, truncate=True)

Detect, using heuristics, whether a string of bytes is text or binary data. If available, this will use the binaryornot lightweight package.

Parameters

  • bytestring (AnyStr) –

  • truncate (bool) –

Return type

bool

comma.helpers module

class comma.helpers.DefaultDialect

Bases: csv.Dialect

The default dialect for output, when no dialect is provided.

classmethod override(**kwargs)

Creates a csv.Dialect object that only overrides certain settings from the default dialect.

Return type

csv.Dialect

comma.helpers.detect_line_terminator(sample, default=None)

Detects the most likely line terminator (from `

`, ` `, ` `), given

a sample string, by counting the occurrences of each pattern and finding the longest and most frequent.

Parameters

  • sample (Optional[AnyStr]) –

  • default (Optional[AnyStr]) –

Return type

str

comma.helpers.has_header(value)

Checks whether a value has a header attribute (that is not None).

Parameters

value (Any) –

Return type

bool

comma.helpers.is_anystr(obj)

Returns True if the obj object is of type typing.AnyStr.

Parameters

obj (Union[Any, AnyStr]) –

Return type

bool

comma.helpers.is_local(location)

Detects whether a string location is a local file path.

Parameters

location (AnyStr) –

Return type

Optional[str]

comma.helpers.is_url(location, no_request=False)

Detects whether a string location is a URL; may make a test HEAD request if the location is likely to be an actual URL (this behavior can be deactivated by setting no_request to True).

Parameters

  • location (str) –

  • no_request (bool) –

Return type

bool

comma.helpers.multislice_index(index, size, slice_list=None)

Returns the original index in the original sequence from the index in the sequence after applying multiple slicing operations. This makes it easier to recover the original index.

Parameters

  • index (int) –

  • size (int) –

  • slice_list (List[slice]) –

Return type

int

comma.helpers.multislice_range(size, slice_list=None)

Returns the range of indexes that are preserved by a succession of slicing operations on the range [0, size). This makes it easier to recover the original index.

Parameters

  • size (int) –

  • slice_list (List[slice]) –

Return type

range

comma.helpers.multislice_sequence(sequence, slice_list=None)

Returns the sub-sequence obtained from sequentially slicing the sequence sequence according to the series of slices in slice_list.

Parameters

  • sequence (Sequence[Any]) –

  • slice_list (List[slice]) –

Return type

Sequence[Any]

comma.helpers.open_csv(source, encoding=None, delimiters=None, no_request=False)

Returns a CommaInfoType typed dictionary containing the data and metadata related to a CSV file. The source can be actual data, a local file path, or a URL; it is possible to provide a stream that is compressed using ZIP.

The source is opened using the comma.helpers.open_stream() helper method. The metadata data is detected using internal helpers and either the csv or clevercsv dialect sniffers.

Parameters

  • source (Union[AnyStr, IO, bytes]) –

  • encoding (str) –

  • delimiters (Optional[Iterable[str]]) –

  • no_request (bool) –

Return type

Dict

comma.helpers.open_stream(source, encoding=None, no_request=False)

Returns a seekable stream for text data that is properly decoded and ready to be read: The source can be actual data, a local file path, or a URL; it is possible to provide a stream that is compressed using ZIP. (This method will store all the data in memory.)

Parameters

  • source (Union[AnyStr, IO, bytes]) –

  • encoding (str) –

  • no_request (bool) –

Return type

Optional[TextIO]

comma.helpers.validate_header(value)

Checks that a value is an iterable of string-like values. And converts to a list of strings. This is to verify user-specified header values.

Parameters

value (Any) –

Return type

List[str]

comma.helpers.zip_html_tag(data, in_pattern="<td style='text-align: left;'>{}</td>", out_pattern='<tr>{}</tr>', indent=0)

Returns the HTML code of a template applied to a Python list; to be used to build the rows of tables, or bullet lists in _repr_html_() outputs.

Parameters

  • data (Iterable) –

  • in_pattern (str) –

  • out_pattern (str) –

  • indent (int) –

Return type

str

comma.methods module

comma.methods.TableType

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Union[comma.classes.table.CommaTable, Iterable[comma.classes.row.CommaRow], Iterable[Iterable[Any]]]

comma.methods.dump(records, filename=None, fp=None, header=None, dialect=None, no_echo=False)

Serializes a table, as specified by records, into CSV format and outputs the result either in a file (if filename is provided), writes it to a stream (if fp is provided) or returns it as a string otherwise.

Optionally allows for a user-specified header, either to provide a header when the records do not have one; or to override existing headers.

Optionally allows for a user-specified dialect (or type csv.Dialect), which will default to comma.helpers.DefaultDialect().

The option no_echo prevents the method from returning the serialized table when it has been output to a file or a stream.

Parameters
Return type

Optional[str]

comma.methods.dumps(records, header=None, dialect=None)

Serializes a table, as specified by records, into CSV format and returns a string.

Optionally allows for a user-specified header, either to provide a header when the records do not have one; or to override existing headers.

Optionally allows for a user-specified dialect (or type csv.Dialect), which will default to comma.helpers.DefaultDialect().

Parameters
Return type

str

comma.methods.load(source, encoding=None, force_header=False, delimiters=None)

Deserializes a table from a CSV/DSV source, and returns a Python list/dict-like object, which is an instance of the comma.classes.table.CommaTable type.

The source can be: A string containing the data directly; a local path to a file containing the data; a URL to the data source. The data can be in any encoding (which will be detected using the BOM if present, or the chardet module otherwise), and it can even be compressed by ZIP.

Although everything is autodetected thanks to clevercsv and chardet, you can optionally use the encoding and delimiters parameters to override (or circumvent) automatic detection.

Parameters

  • source (Union[AnyStr, IO, bytes]) –

  • encoding (str) –

  • force_header (bool) –

  • delimiters (Optional[Iterable[str]]) –

Return type

Optional[comma.classes.table.CommaTable]

comma.typing module

comma.typing.CommaInfoParamsType

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Dict

comma.typing.CommaInfoType

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Dict

comma.typing.DialectType

alias of csv.Dialect

comma.typing.HeaderType

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Union[List, Iterable[Any]]

comma.typing.SimpleDialectType

alias of clevercsv.dialect.SimpleDialect

comma.typing.SourceType

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Union[AnyStr, IO, bytes]

comma.typing.TypedDict(name, dict_type)
Parameters

  • name (str) –

  • dict_type (Dict) –

Return type

type

Module contents

Library to make CSV reading/writing fun and enjoyable!