xocto 2.0

Kraken Technologies Python service utilities

xocto - utilities for Python services

This repo houses various shared utilities for Python services at Kraken Technologies.

This library works with Python 3.8 and above.

CI status:

PyPI detail page: https://pypi.python.org/pypi/xocto

Functionality

Event publishing

Use events.publish to publish application events. These will be logged as JSON to a logger named "events".

Sample usage:

from xocto import events

events.publish(
    event="ACCOUNT.CREATED",
    params={
        'name': 'Barry Chuckle',
        'quote_id': 'xyz123',
    },
    meta={
        'account_id': 'A-12312345'
    },
    account=account,  # optional
    request=request,  # optional
)

Event timing

Time events using:

from xocto import events

with events.Timer() as t:
    # do some things

events.publish(
    event="SOMETHING.HAPPENED",
    meta={
        "duration_in_ms": t.duration_in_ms
    }
)

Ranges

The ranges module is, as the name suggests, a utility for working with ranges.

The most basic building block of the module is the Range class.

A few basic examples of its usage:

from xocto.ranges import Range, RangeBoundaries

>>> Range(0, 2, boundaries=RangeBoundaries.EXCLUSIVE_INCLUSIVE)
<Range: (0,2]>
>>> Range(0, 2, boundaries="[]")
<Range: [0,2]>
>>> sorted([Range(1, 4), Range(0, 5)])
[<Range: [0,5)>, <Range: [1,4)>]
>>> sorted([Range(1, 2), Range(None, 2)])
[<Range: [None,2)>, <Range: [1,2)>]
>>> sorted([Range(3, 5), Range(3, 4)])
[<Range: [3,4)>, <Range: [4,5)>]

See xocto.ranges for more details, including examples and in depth technical details.

Numbers

The numbers module is intended as your one-stop shop for all things numbers.

An example of rounding a number to an arbitrary integer base:

from xocto.numbers import quantise

>>> quantise(256, 5)
255

See xocto.numbers for more details, including examples and in depth technical details.

The localtime module

This module is a battle tested and well reviewed module for working with dates, times and timezones.

It's been over the years internally in Kraken Technologies, and is used heavily internally.

The main API it presents is composed of a series of functions which accept a date/datetime object, and manipulate it in one form or another.

Examples of a few of those:

from xocto import localtime
>>> now = localtime.now()
>>> now
2022-04-20 14:57:53.045707+02:00
>>> localtime.seconds_in_the_future(n=10, dt=now)
2022-04-20 14:58:03.045707+02:00
>>> localtime.nearest_half_hour(now)
2022-04-20 15:00:00+02:00

See xocto.localtime for more details, including examples and in depth technical details.

Development

Installation

Create and activate a Python 3.8 virtualenv then run:

make install

to install the package including development and testing dependencies

Running tests

Run the test suite with:

make test

Running static analysis

Use these make commands

make lint
make black
make isort

Docker images for these jobs can be built with:

make docker_images

This creates separate images for pytest, isort and black. Each can be run like so:

docker run -v `pwd`:/opt/app xocto/pytest
docker run -v `pwd`:/opt/app xocto/isort
docker run -v `pwd`:/opt/app xocto/black

Publishing

Release to PyPI by:

1. Bumping the version in setup.py

2. Updating CHANGELOG.md

3. Committing:

   git commit -am "Bump version to v..."
   

4. Running:

   make publish