POP Version 26: Introducing Stacky Ordered Contracts

Plugin Oriented Programming (POP) continues to evolve, and with version 26, we're excited to introduce some notable advancements. This release not only enhances the existing Contract Ordering system but also unveils a new concept known as "Stacky" contracts.

Overview

The Contract Ordering feature in POP orchestrates the sequence of contract execution into three distinct categories:

1. Positive Ordering: Contracts with a positive ``__order__`` value are executed first, starting with the lowest positive value.

2. Default Ordering: Contracts without an ``__order__`` attribute are executed after positive ones, maintaining their original load order.

3. Negative Ordering: Contracts with a negative ``__order__`` value are executed last, in descending order.

Order Verification

The new __verify_order__ function for contracts offers developers the ability to introduce custom order verification logic. This optional attribute adds a layer of control and validation, allowing you to ensure that contracts are executed in the desired sequence.

It's invoked after the sorting of contracts based on their __order__ values and before execution of the functions they govern, providing an opportunity to double-check the order integrity.

Example Usage:

Suppose you want to check a specific condition in your contract execution sequence. You can use the __verify_order__ function to achieve this.

# project_root/pop_code/mod/contracts/contract_name.py

def __verify_order__(hub, contracts:list):
    # custom logic to verify order
    if some_condition: # Replace with your specific check
        return False, "Order verification failed"
    return True

In this example, the __verify_order__ function is checking "some_condition". If it fails, the function returns False and a message explaining why the verification failed, which raises an error. Otherwise, it returns True, signaling that the order verification was successful. The "contracts" parameter contains a list of the full LoadedMod objects for the contracts in the final order that they will be exectuted in.

This flexibility allows you to build in complex checks and ensures that the contracts are executed precisely as you intend. The ability to custom verify the order adds an extra layer of reliability and predictability to your system.

Introducing Stacky Contracts

With POP Version 26, we're excited to present a fresh concept in contract execution: Stacky contracts. This idea redefines the way "post" contracts are executed, creating an intuitive and robust method for handling sequences.

In traditional POP architecture, "pre" contracts are executed in the order they are defined, followed by "post" contracts in the same sequence. Stacky contracts alter this flow, executing "post" contracts in reverse order of the corresponding "pre" contracts.

Stacky contracts bring a new dimension of control and flexibility. By executing "post" contracts in reverse order, you can create more complex interactions and dependencies between contracts, mirroring the unwinding of actions performed in "pre" contracts.

Example Usage:

Consider the following contracts that wrap a "run" function:

# project_root/pop_code/module1.py
__order__ = 100

def pre_run(hub, ctx):
    print("this runs first")

def post_run(hub, ctx):
    print("this runs last")

And a second contract with a higher order that wraps the same "run" function:

# project_root/pop_code/module2.py
__order__ = 200

def pre_run(hub, ctx):
    print("This runs second")

def post_run(hub, ctx):
    print("This runs second to last")

In this example, Module 1's pre_run function with an __order__ of 100 prints "this one runs first," and Module 2's pre_run function with an __order__ of 200 prints "this runs second." Then, the post_run functions execute in reverse order: Module 2's prints "this runs second to last," and Module 1's prints "this one runs last."

This adjustment to contract ordering is a substantial addition to the Plugin Oriented Programming paradigm, offering an exact and predictable method for executing contract sequences. It's a tool that can enhance your development, unlocking more sophisticated and responsive interactions in your code.

Modularity in POP: Contracts as Mods

Remember, in the Plugin Oriented Programming (POP) framework, contracts themselves are treated as mods. This offers a unique way to ensure intricate contract ordering and execution scenarios. You can even have contracts on contracts, extending flexibility in controlling how they interact and execute.

Explore this concept and use it to meet your specific requirements as you get more comfortable with POP.

Example Usage:

# project_root/pop_code/mod/contracts/contracts/init.py

def pre_pre(hub, ctx):
    # This contract would run before "pre" contracts in project_root/pop_code/mod/contracts/contract_name.py
    ...

def post_pre(hub, ctx):
    # This contract would run after "pre" contracts in project_root/pop_code/mod/contracts/contract_name.py
    ...

def sig_post(hub, ctx):
    # This contract ensures that a "post" contract exists in project_root/pop_code/mod/contracts/contract_name.py
    ...

Embracing this approach opens doors for more nuanced ordering of your contracts, paving the way for complex interactions tailored to your needs. It's a neat trick that amplifies the flexibility and dynamism in POP, especially for those ready to venture into advanced contract handling.