soco.utils module

This class contains utility functions used internally by SoCo.

soco.utils.really_unicode(in_string)

Make a string unicode. Really.

Ensure in_string is returned as unicode through a series of progressively relaxed decodings.

Parameters

in_string (str) – The string to convert.

Returns

Unicode.

Return type

str

Raises

ValueError –

soco.utils.really_utf8(in_string)

Encode a string with utf-8. Really.

First decode in_string via really_unicode to ensure it can successfully be encoded as utf-8. This is required since just calling encode on a string will often cause Python 2 to perform a coerced strict auto-decode as ascii first and will result in a UnicodeDecodeError being raised. After really_unicode returns a safe unicode string, encode as utf-8 and return the utf-8 encoded string.

Parameters

in_string – The string to convert.

soco.utils.camel_to_underscore(string)

Convert camelcase to lowercase and underscore.

Recipe from http://stackoverflow.com/a/1176023

Parameters

string (str) – The string to convert.

Returns

The converted string.

Return type

str

soco.utils.prettify(unicode_text)

Return a pretty-printed version of a unicode XML string.

Useful for debugging.

Parameters

unicode_text (str) – A text representation of XML (unicode, not utf-8).

Returns

A pretty-printed version of the input.

Return type

str

soco.utils.show_xml(xml)

Pretty print an ElementTree XML object.

Parameters

xml (ElementTree) – The ElementTree to pretty print

Note

This is used a convenience function used during development. It is not used anywhere in the main code base.

class soco.utils.deprecated(since, alternative=None, will_be_removed_in=None, alternative_not_referable=False)

A decorator for marking deprecated objects.

Used internally by SoCo to cause a warning to be issued when the object is used, and marks the object as deprecated in the Sphinx documentation.

Parameters

• since (str) – The version in which the object is deprecated.

• alternative (str, optional) – The name of an alternative object to use

• will_be_removed_in (str, optional) – The version in which the object is likely to be removed.

• alternative_not_referable (bool) – (optional) Indicate that alternative cannot be used as a sphinx reference

Example

@deprecated(since="0.7", alternative="new_function")
def old_function(args):
    pass

soco.utils.url_escape_path(path)

Escape a string value for a URL request path.

Parameters

str – The path to escape

Returns

The escaped path

Return type

str

>>> url_escape_path("Foo, bar & baz / the hackers")
u'Foo%2C%20bar%20%26%20baz%20%2F%20the%20hackers'

soco.utils.first_cap(string)

Return upper cased first character