Skip to main content

Programming by contract

Project description

Deal

Build Status Coverage Status PyPI version Development Status

Deal -- python library for design by contract (DbC) programming.

That's nice assert statements in decorators style to validate function input, output, available operations and object state. Goal is make testing much easier and detect errors in your code that occasionally was missed in tests.

Features

Available decorators

CLassic DbC:

  • deal.pre -- validate function arguments (pre-condition)
  • deal.post -- validate function return value (post-condition)
  • deal.ensure -- post-condition that accepts not only result, but also function arguments.
  • deal.inv -- validate object internal state (invariant).

Take more control:

Helpers:

  • deal.chain -- chain a few contracts in one.
  • deal.pure -- forbid side-effects and combine safe, silent, and offline.
  • deal.safe -- forbid exceptions.

Installation

python3 -m pip install --user deal

Quick Start

import re

import attr
import deal

REX_LOGIN = re.compile(r'^[a-zA-Z][a-zA-Z0-9]+$')

class PostAlreadyLiked(Exception):
    pass

@deal.inv(lambda post: post.visits >= 0)
class Post:
    visits: int = attr.ib(default=0)
    likes: set = attr.ib(factory=set)

    @deal.pre(lambda user: REX_LOGIN.match(user), message='invalid username format')
    @deal.raises(PostAlreadyLiked)
    @deal.chain(deal.offline, deal.silent)
    def like(self, user: str) -> None:
        if user in self.likes:
            raise PostAlreadyLiked
        self.likes.add(user)

    @deal.post(lambda result: 'visits' in result)
    @deal.post(lambda result: 'likes' in result)
    @deal.post(lambda result: result['likes'] > 0)
    @deal.pure
    def get_state(self):
        return dict(visits=self.visits, likes=len(self.likes))

Now, Deal controls conditions and states of the object at runtime:

  1. @deal.inv controls that visits count in post always non-negative.
  2. @deal.pre checks user name format. We assume that it should be validated somewhere before by some nice forms with user-friendly error messages. So, if we have invalid login passed here, it's definitely developer's mistake.
  3. @deal.raises says that only possible exception that can be raised is PostAlreadyLiked.
  4. @deal.chain(deal.offline, deal.silent) controls that function has no network requests and has no output in stderr or stdout. So, if we are making unexpected network requests somewhere inside, deal let us know about it.
  5. deal.post checks result format for get_state. So, all external code can be sure that fields likes and visits always represented in the result and likes always positive.

If code violates some condition, sub-exception of deal.ContractError will be raised:

p = Post()
p.visits = -1
# InvContractError:

Dive deeper on deal.readthedocs.io.

Contributing

Contributions are welcome! A few ideas what you can contribute:

  • Add new checks for the linter.
  • Improve documentation.
  • Add more tests.
  • Improve performance.
  • Found a bug? Fix it!
  • Made an article about deal? Great! Let's add it into the README.md.
  • Don't have time to code? No worries! Just tell your friends and subscribers about the project. More users -> more contributors -> more cool features.

Thank you :heart:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for deal, version 3.9.0
Filename, size File type Python version Upload date Hashes
Filename, size deal-3.9.0-py3-none-any.whl (96.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size deal-3.9.0.tar.gz (43.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page