Package: contractsPY
Python Business Transactions Library - ContractsPYDeclare and define business transactions in Python. Use the contracts library to
validate business transactions with Railway-oriented approach.CompatibilityTested on Python 3.8+InstallationThere is no additional dependencies. Library's footprint is small.>>>pipinstallcontractsPYContract functionsContract functions are simple python functions that return True or False. They are
used to define business rules for transactions. They accept only one argument,
which is the current state of the transaction.defmy_contract(state):returnstate.a>state.bif_fails decoratorYou can use theif_failsdecorator to define a message if the contract fails. This decorator
is optional. If you don't use it, the message will be the name of the contract function.State objectAll contract functions accept a single argument, which is the current state of the transaction.
State is the dictionary that contains all the data of the transaction. You can set and get
values from the state. For example:state.a = 10orstate.b = state.a + 1. Remember that, state keys are immutable. So, you can't change the state key-value pairs after you set them. For example, you can't dostate.a = 10and thenstate.a = 20.Example (Create User):Let's assume we have a user service that creates a new user. There are multiple steps to create a new user.First, we need to validate the user's data.Then, we need to make sure that the user doesn't already exist.We need to save the user to the database.We need to send an email to the user.There are many ways to do this. We can use the contracts library to make it easier and more readable.
All you need to do is to define a contract for each step. I can hear you saying "Why do I need to make things like this?". Well, I'm glad you asked.Railway-oriented approach:As we mentioned before, the contractsPY library uses the Railway-oriented approach. This approach helps you to handle every possible scenario on the way to the final step. That's why they called it "Railway-oriented".Whenever you call a function, there are two possible returns (success and failure). Your business logic is executed in the success case. If the business logic fails, you can handle the failure case.fromcontractspyimportif_fails,Usecase@if_fails(message="Not validated.")defvalidate_inputs(state):ifstate.passwordandstate.username:returnTruereturnFalse@if_fails(message="User not generated.")defgenerate_user(state):state.user=User(state.username,state.password)returnTrueifstate.userelseFalse@if_fails(message="User exists.")defvalidate_user_exists(state):foruserinusers:ifuser.username==state.user.username:returnFalsereturnTrue@if_fails(message="User not saved.")defpersist_user(state):users.append(state.user)returnTrueifstate.userelseFalseregister_user=Usecase()register_user.contract=[validate_inputs,generate_user,validate_user_exists,persist_user]if__name__=='__main__':result=register_user.apply(username='johndoe',password='foobar')print(result)Result:As you can see from the Result, user was not created. The reason is that the user already exists.
Now, we can handle the failure case, and send proper error messages to the user.>>>Result(state={'username':'johndoe','password':'foobar','user':User(username=johndoe,password=foobar)},case=error,message='User exists.')The result object contains three fields. State, case, message. You can check the case and message to see what went wrong. If everything went well, you can pick a value from the state dictionary.result.state={'username':'johndoe','password':'foobar','user':User(username=johndoe,password=foobar)}result.case=errorresult.message='User exists.'If there was no failure, the result should have been like this:>>>Result(state={'username':'johndoe','password':'foobar','user':User(username=johndoe,password=foobar)},case=success,message='Ok')(C) Arzu Hussein