pysharedutils Documentation

Transcription

1 pysharedutils Documentation Release Joel James August 07, 2017

2

3 Contents 1 pysharedutils 1 2 Indices and tables 13 i

4 ii

5 CHAPTER 1 pysharedutils pysharedutils is a convenient utility module which are not included in standard Python install. Installation pysharedutils is available on PyPI, so to use it you can use pip: To install pysharedutils, simply run: $ pip install pysharedutils Alternatively, if you don t have setuptools installed, download it from PyPi and run: $ python setup.py install Also, you can get the source from GitHub and install it as above: $ git clone $ cd pysharedutils $ python setup.py install Examples Some quick usage examples. Changes See the Changelog for a full list of changes to py-shared-utils. Note: Always read changelog documentation before putting updates live in production. Offline Documentation Download the docs in pdf or epub formats for offline reading. 1

6 Contribute Always looking for contributions, additions and improvements. The source is available on GitHub and contributions are always encouraged. To contribute, fork the project on GitHub and submit a pull request. If you have notices bugs or issues with the library, you can add it to the Issue Tracker. Install development requirements. It is highly recommended that you use a virtualenv, and activate the virtualenv before installing the requirements. Install project requirements: $ pip install -r requirements.txt Run tests with coverage: $ make unit_test Run test Using Tox (Runs the tests in different supported python interpreter): $ tox Run Lint: $ make lint Create a new local branch to submit a pull request: $ git checkout -b name-of-feature Commit your changes: $ git commit -m "Detailed commit message" Push up your changes: $ git push origin name-of-feature Submit a pull request. Before submitting a pull request, make sure pull request add the functionality, it is tested and docs are updated. Examples Some quick usage examples. Getting started If you haven t installed pysharedutils, simply use pip to install it like so: $ pip install pysharedutils 2 Chapter 1. pysharedutils

7 Attrs get_object_by_source: Tries to get the object by source. Similar to Python s getattr(obj, source), but takes a dot separated string for source to get source from nested obj, instead of a single source field. Also, supports getting source form obj where obj is a dict type. Signature: get_object_by_source(obj, source, allow_blank_source=false) obj A python object or a python dict. source The source name which has to be extracted from the object. You can use dot syntax to specify nested source. allow_blank_source (Default: False) A bool, if set to True it catches AttributeError and returns None if the source does not exist on the obj. Example with python object: class User: def init (self, , username): self. = self.username = username obj = User( ='foo.example.com', username='foobar') pysharedutils.get_object_by_source(obj=obj, source=' ') # 'foo.example.com' Example with python dict: obj = {'user': {'username': 'foobar', ' ': 'foo.example.com' pysharedutils.get_object_by_source(obj=obj, source='user.username') # 'foobar' Dates utc_now: Returns current UTC time and sets the time zone info to UTC. Signature: utc_now() pysharedutils.utc_now() output.utc_now() # datetime.datetime(2016, 9, 21, 18, 56, 53, , tzinfo=<utc>) Decorators singleton: Decorator that creates a singleton instance. If the method is called later a cached instance of the method is returned Contribute 3

8 @pysharedutils.singleton def some_method(self): return 'Something' memoize: Decorator that caches a function s return value each time it is called. If called later with the same arguments, the cached value is returned, and the method is not def some_method(self, arg1, arg2): # Perform some heavy computation return 'Something' cached_property: Decorator that caches the property on the instance. Computed only once per instance. class def very_slow(self): time.sleep(1) return "Slow class" SlowClass().very_slow Dicts ObjectDict: Helper class that makes a dictionary behave like an object, with attribute-style access (read and write). Signature: ObjectDict(d) d A python dict object. data = { 'name': 'foo', 'nesting': { 'nested_key': 'val', 'inner_nesting': 'inner_nesting_val' 4 Chapter 1. pysharedutils

9 , 'some_list': [ { 'foo': 'bar' ] output = pysharedutils.objectdict(data) output.name # 'foo' output.nesting.nested_key # 'val' output.some_list[0].foo # 'bar' # You can also set variables using dot syntax object_dict = pysharedutils.objectdict(data) object_dict.gender = 'Male' object_dict.gender # 'Male' MultiDict: Extends a python dict type by adding getlist method. Signature: MultiDict(dict) output = pysharedutils.multidict({'username': 'foobar') output.getlist('username') # ['foobar'] compact_dict: Creates a dict with all falsey values removed. Signature: compact_dict(obj) obj A dict who s falsey values has to be removed. data = { 'username': 'foobar', 'name': '', 'comment': { 'line_1': 'abc', 'line_2': '', 'inner_nesting': { 'key': 'value', 'blank': None, 'location': [ { 'address_1': '', 'city': 'Baton Rouge', 'inner_nesting': { 'key': 'value', 1.4. Contribute 5

10 'blank': None ] pysharedutils.compact_dict(data) # {'username': 'foobar', 'comment': {'line_1': 'abc', 'inner_nesting': {'key': 'value', 'location': merge_dicts: Merges all of the given dicts together. Signature: compact_dict(*dicts) d1 = {'a': 'apple' d2 = {'b': 'ball' pysharedutils.merge_dicts(d1, d2) # {'a': 'apple', 'b': 'ball' snake_case_dict_keys: Maps the keys of the dict from camel case to snake case. Signature: snake_case_dict_keys(obj) pysharedutils.snake_case_dict_keys({'camelcase': 'camel_case') # {'camel_case': 'camel_case' camel_case_dict_keys: Maps the keys of the dict from snake case to camel case. Signature: camel_case_dict_keys(obj, upper=false) obj A python dict object. upper A bool, default False. If set to True will convert the keys to upper camel case else will conver the keys to lower camel case. pysharedutils.camel_case_dict_keys({'snake_case': 'snake_case') # {'snakecase': 'snake_case' pysharedutils.camel_case_dict_keys({'snake_case': 'snake_case', upper=true) # {'SnakeCase': 'snake_case' get_dict_properties: Get multiple key value from a dict in one call. Signature: get_dict_properties(obj, *args) obj A python dict object. 6 Chapter 1. pysharedutils

11 strict A bool, if set to False will ignore AttributeError when trying to get non-existing propert on the object. *args Property names which has to be fetched from the dict. You can also use dot separated names to get properties from nested dicts. See example below. d = { 'first_name': 'Foo', 'last_name': 'Bar', 'comment': { 'message': 'some text', 'user': { 'username': 'foo.bar.com' pysharedutils.get_dict_properties( d, False, 'first_name', 'zipcode', 'comment.message', 'comment.location', 'comment.user.username' ) # {'first_name': 'Foo', 'comment.user.username': 'foo.bar.com', 'zipcode': None, 'comment.location': map_dict_keys: Maps the keys of a dict with the map keys. Signature: map_dict_keys(obj, map_obj) obj A python dict object who s keys has to be mapped. map_obj A map dict specifying the key and the new key. obj = { 'first_name': 'Joe', 'user': { 'contact': { ' ': 'joe@example.com', 'address': { 'line_1': 'address line 1' map_obj = { 'first_name': 'given_name', 'user.contact. ': 'user.contact.contact_ ', 'user.contact.address.line_1': 'user.contact.address_1', pysharedutils.map_dict_keys(obj, map_obj) # {'user': {'contact': {'contact_ ': 'joe@example.com', 'address': {'address_1': 'address line 1' 1.4. Contribute 7

12 Encodings force_bytes: Forces the value to a bytes instance. Signature: force_bytes(value, encoding= utf-8, strings_only=true, errors= strict ) value A value which has to be converted to a bytes. encoding (Default: utf-8 ) The encoding type. strings_only (Default: True) A bool, if set to True will ignore decoding values which are None or int. errors (Default: strict ) The error level when encoding. pysharedutils.force_bytes('some_string') # b'some_string' force_str: Forces the value to a str instance, decoding if necessary. Signature: force_str(value, encoding= utf-8 ) value A value which has to be converted to a string. encoding (Default: utf-8 ) The string encoding. pysharedutils.force_str(b'some_byte_string') # 'some_byte_string' Functions import_by_path: Imports a class or module by path(dot syntax). Raise ImportError if the import failed. Signature: import_by_path(path) path The path to the class that has to be imported. pysharedutils.import_by_path('pysharedutils.functions.import_by_path') # <function import_by_path at 0x103d2d5f0> Lists compact_list: Creates an list with all falsey values removed. Signature: compact_list(arr) 8 Chapter 1. pysharedutils

13 arr A list who s falsey values has to be removed. pysharedutils.compact_list([false, 1, '', {]) # [1] force_list: Force the given object to be a list, wrapping single objects. Signature: force_list(obj) obj A obj which has to be converted to list. pysharedutils.force_list('name') # ['name'] flatten_list: Creates an a flattened list. Signature: flatten_list(arr) arr A list which has to be flattened. pysharedutils.flatten_list([1, [2, [3, [4]], 5]]) # [1, 2, 3, 4, 5] list_intersection: Return the intersection of the two lists. Signature: list_intersection(arr1, arr2) arr1 A list that has to be intersected. arr2 A list that has to be intersected. pysharedutils.list_intersection([1, 2], [1]) # [1] list_find: Iterates over elements of collection, returning the first element predicate returns truthy for. Signature: list_find(predicate, coll, from_index=0) predicate The function invoked per iteration. coll The collection to inspect. from_index Default(0) The index to search from Contribute 9

14 def predicate(value): if value > 40: return True pysharedutils.list_find(predicate, [1, 2, 41, 80]) # 41 Strings camel_to_snake_case: Converts a camel case word to snake case. Signature: camel_to_snake_case(word) word A string that needs to be converted to snake case. pysharedutils.camel_to_snake_case('camelcase') # 'camel_case' snake_to_camel_case: Converts a snake case word to camel case. Signature: snake_to_camel_case(word, upper=false) word A string that needs to be converted to camel case. upper A bool, default False. If set to True will convert the word to upper camel case else will conver the word to lower camel case. pysharedutils.snake_to_camel_case('snake_case') # 'snakecase' pysharedutils.snake_to_camel_case('snake_case', upper=true) # 'SnakeCase' equals: Returns True if the two strings are equal, False otherwise. The time taken is independent of the number of characters that match. For the sake of simplicity, this function executes in constant time only when the two strings have the same length. It short-circuits when they have different lengths. Signature: equals(val1, val2) val1 A string that has to be compared. val2 A string that has to be compared. pysharedutils.equals('some_value', 'some_value') # True 10 Chapter 1. pysharedutils

15 Changelog Changes in v0.5.0 Add support for upper camel case conversion. Changes in v0.4.2 Fixes bug in compact_dict where compact dict did not work if a last of non dicts were passed in. Changes in v0.4.1 Added support for get, pop on ObjectDict. Changes in v0.4.0 Added support for get_dict_properties, which adds ability to get multiple key value from a dict in one call. Added support for map_dict_keys, which adds ability to map the keys of a python dict with map value. Changes in v0.3.0 Added convenient python utility modules which are not included in python standard lib Contribute 11

16 12 Chapter 1. pysharedutils

17 CHAPTER 2 Indices and tables genindex modindex search 13