soco.utils module

This class contains utility functions used internally by SoCo.

soco.utils.really_unicode(in_string)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Return upper cased first character