Design Principles

These are the principles that guide development of the Amatino Python library. They are not hard-and-fast rules, but guidance that may be adjusted through debate.

• Strict dynamic type checking
• Optional static type checking
• Immutable objects
• No third party dependencies
• Aesthetics

Strict dynamic type checking

Amatino Python aims to be as easy to integrate as possible. It should clearly signal its expectations, and signal failure as early in execution as possible. To that end, all Amatino code should enforce strict dynamic type checking. For example, if a function expects a str argument, and it is not provided with an instance of str, it should immediately raise a TypeError.

The alternative is to fail in some derived manner. For example, an incorrect input type might manifest itself as a 400 - Bad Request response from the Amatino API. The reason for the failure is now obfuscated behind several layers of the call stack.

By enforcing strict dynamic type checking, Amatino Python makes the reasons for failure absolutely clear, close to the root cause of the failure. TypeError descriptions should be concise, explicit, and comprehensive. For example:

def expects_string(foo: str):
   if not is instance(foo, str):
      raise TypeError('foo must be of type `str`')
   # ...

expects_string(1) # Immediate and clear feedback

Optional static type checking

Some developers choose to enforce static type checking on their Python software. Amatino Python should meet the same standard of typing that such developers expect of their own code. Anything less would introduce a reason to avoid Amatino Python.

Static type checking is provided by strict PEP 484 compliance, up to that which may be interpreted by Python 3.4. During development, Amatino Python code should be linted by mypy or similarly PEP 484 compliant linting library.

Of course, static checking is optional. A developer who is unfamiliar with static type-checking, or wishes not to employ it, should be in no way inconvenienced or hindered by its inclusion. In fact, they should not even notice static checking exists.

Immutable Objects

All Amatino objects should be immutable. Immutability is desired because it reduces cognitive load on the developer. When working with an immutable object, the developer need only reason about what the object is and what it does. They do not need to reason, as is the case with a mutable object, about the object's state.

Immutability should be clearly and explicitly signalled. An attempt to mutate object state should raise an informative error. For example:

transaction = Transaction()
transaction.description = 3 # Should raise error

No third party dependencies

When a developer is considering including Amatino in their project, they should only need to consider the inclusion of Amatino itself. They should not need to consider the inclusion of other libraries.

Amatino should require no third party dependencies beyond the Python standard library.

There is one exception: The typing module. typing walks in a netherworld between the standard library and third-party dependency, being a back port of PEP484 to older Python versions. Excluding it would, in combination with the principle of including strong static type checking, preclude installation of Amatino on older Python versions.

Aesthetics

• No more than 80 characters per line
• General compliance with PEP-8