Merge pull request #9 from octoenergy/docs

Various project improvements

Author: codeinthehole

.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 jobs:
   build:
     docker:
-      - image: octoenergy/consumer-site-circle-docker:1.12
+      - image: cimg/python:3.8.13
     steps:
       - checkout
       - run:

.gitignore

@@ -13,8 +13,10 @@ eggs
 develop-eggs
 
 # Testing and local development
+.python-version
 .idea
 .cache
+.hypothesis
 
 # Local temporary files
 .DS_Store

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.7.7-slim AS base
+FROM python:3.8.13-slim AS base
 
 # Create virtualenv and add to path.
 ENV VIRTUAL_ENV=/opt/venv
@@ -12,8 +12,7 @@ WORKDIR /opt/app
 
 # Install Python requirements. README.md is required as the setup.py file
 # refers to it.
-COPY README.md .
-COPY setup.py .
+COPY . .
 RUN pip install -e .[dev,test]
 
 # Run subsequent commands as non-root user

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2018 Octopus Energy Ltd and individual contributors.
+Copyright (c) 2016-2018 Kraken Technologies Ltd and individual contributors.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -11,7 +11,7 @@ are permitted provided that the following conditions are met:
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
 
-    3. Neither the name of Octopus Energy Ltd nor the names of its contributors 
+    3. Neither the name of Kraken Technologies Ltd nor the names of its contributors 
        may be used to endorse or promote products derived from this software without
        specific prior written permission.
 

README.md

@@ -1,29 +1,32 @@
 # xocto - utilities for Python services
 
-This repo houses various shared utilities for Python services at Octopus Energy.
+This repo houses various shared utilities for Python services at Kraken
+Technologies.
+
+This library works with Python 3.8 and above.
 
 CI status:
 
 [![CircleCI](https://circleci.com/gh/octoenergy/xocto/tree/master.svg?style=svg)](https://circleci.com/gh/octoenergy/xocto/tree/master)
 
-PyPI detail page: https://pypi.python.org/pypi/xocto
+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". 
+to a logger named "events".
 
 Sample usage:
 
 ```python
 from xocto import events
 
 events.publish(
-    event="ACCOUNT.CREATED", 
+    event="ACCOUNT.CREATED",
     params={
-        'name': 'Barry Chuckle', 
+        'name': 'Barry Chuckle',
         'quote_id': 'xyz123',
     },
     meta={
@@ -47,7 +50,7 @@ with events.Timer() as t:
 events.publish(
     event="SOMETHING.HAPPENED",
     meta={
-        "duration_in_ms": t.duration_in_ms 
+        "duration_in_ms": t.duration_in_ms
     }
 )
 ```
@@ -75,13 +78,15 @@ from xocto.ranges import Range, RangeBoundaries
 [<Range: [3,4)>, <Range: [4,5)>]
 ```
 
-See [xocto.ranges](xocto/ranges.py) for more details, including examples and in depth technical details.
+See [`xocto.ranges`](xocto/ranges.py) 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:
+
 ```python
 from xocto.numbers import quantise
 
@@ -93,11 +98,14 @@ See [xocto.numbers](xocto/numbers.py) for more details, including examples and i
 
 ### The localtime module
 
-This module is a battle tested and well reviewed module for working with dates, times and timezones.
+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.
+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.
+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:
 
@@ -114,43 +122,67 @@ from xocto import localtime
 
 See [xocto.localtime](xocto/localtime.py) for more details, including examples and in depth technical details.
 
+## Development
+
+### Installation
+
+Create and activate a Python 3.8 virtualenv then run:
+
+```sh
+make install
+```
 
-## Contributing
+to install the package including development and testing dependencies
 
-Create and activate a virtualenv then:
+### Running tests
 
-    $ make
+Run the test suite with:
 
-Test package locally with:
+```sh
+make test
+```
 
-    $ make test
+### Running static analysis
 
-and:
+Use these make commands
 
-    $ make lint  
+```sh
+make lint
+make black
+make isort
+```
 
-Development docker images can be built with:
+Docker images for these jobs can be built with:
 
-    $ make docker_images
+```sh
+make docker_images
+```
 
-which creates separate images for pytest, isort and black. Each can be run like so:
+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
+```sh
+docker run -v `pwd`:/opt/app xocto/pytest
+docker run -v `pwd`:/opt/app xocto/isort
+docker run -v `pwd`:/opt/app xocto/black
+```
 
-## Release new version
+### Publishing
 
 Release to PyPI by:
 
 1. Bumping the version in `setup.py`
 
 2. Updating `CHANGELOG.md`
 
-3. Committing
+3. Committing:
 
-        $ git commit -am "Bump version to v..."
+   ```sh
+   git commit -am "Bump version to v..."
+   ```
 
-4. Running: 
+4. Running:
 
-        $ make publish
+   ```sh
+   make publish
+   ```

setup.py

@@ -13,36 +13,36 @@
 setup(
     name="xocto",
     version=VERSION,
-    description="Octopus Energy Python service utilities",
+    description="Kraken Technologies Python service utilities",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/octoenergy/xocto",
-    author="Octopus Energy",
+    author="Kraken Technologies",
     author_email="talent@octopus.energy",
     license="MIT",
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",
         "Topic :: Software Development :: Build Tools",
         "License :: OSI Approved :: MIT License",
-        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.8",
     ],
     packages=["xocto", "xocto.events"],
     package_data={"xocto": ["py.typed"]},
     zip_safe=False,
     install_requires=[
-        "pytz==2022.1",
-        "django==3.2.13",
-        "structlog==20.2.0",
-        "python-dateutil==2.8.2",
+        "pytz",
+        "django>=3.2,<4.0",
+        "structlog>=20.2.0",
+        "python-dateutil>=2.8.2",
     ],
     extras_require={
-        "dev": ["wheel==0.29.0", "twine==1.8.1", "black==22.3.0", "isort==5.10.1"],
+        "dev": ["wheel==0.37.1", "twine==4.0.0", "black==22.3.0", "isort==5.10.1"],
         "test": [
             "flake8==4.0.1",
-            "pytest==7.0.1",
+            "pytest==7.1.2",
             "pytest-django==4.5.2",
-            "hypothesis==5.49.0",
+            "hypothesis==6.45.1",
             "time-machine==2.6.0",
         ],
     },