swchcapreg

library to handle capacity registry

Python library package

This project is published as swchcapreg and imported as swch_capreg.

• Public class: swch_capreg.SwChCapacityRegistry

Installation

Requires Python 3.12+.

Install from package index:

pip install swchcapreg==0.1.1

Or install/upgrade to the latest available release:

pip install -U swchcapreg

Quick start

from swch_capreg import SwChCapacityRegistry

capreg = SwChCapacityRegistry("ra-example")
capreg.initialize_capacity_from_file("sztaki-capacity-raw.yaml")
offers = capreg.resource_offer_generate_from_SAT_file("swarm1", "BookInfo.yaml")
print(offers)

Public API (selected)

Core classes

• SwChCapacityRegistry: orchestrates capacity loading, offer generation, acceptance/rejection, and resource state transitions.

Exposed registry methods

The following methods are the documented API entry points of SwChCapacityRegistry.

API Reference Table

Method	Signature	Summary
initialize_capacity_by_content	(content: str)	Initialize capacity from YAML content string.
initialize_capacity_from_file	(filename: str)	Initialize capacity from CDT YAML file.
resource_offer_generate_by_SAT_content	(swarmid: str, sat_content: str)	Generate offers from SAT YAML content.
resource_offer_generate_from_SAT_file	(swarmid: str, sat_filename: str)	Generate offers from SAT file and reserve resources.
resource_offer_query_all	(swarmid: str)	Return all offers for a swarm.
resource_offer_accept	(offerid: str, offer: list | dict)	Accept an offer (reserved → assigned).
resource_offer_reject	(offerid: str, offer: list | dict)	Reject an offer (reserved → free) and remove it.
resource_set_get_from_offer	(offerid: str, offer: list | dict)	Build normalized resource-set descriptor from an offer.
resource_set_deployed	(swarmid: str, msid: str, restype: str, resid: str, count: int)	Mark assigned resources as deployed (assigned → allocated).
resource_set_undeployed	(swarmid: str, msid: str, restype: str, resid: str, count: int)	Mark deployed resources as undeployed (allocated → assigned).
resource_set_query_all	(swarmid: str, msid: str | None = None)	Query tracked resource states for a swarm or microservice.
resources_and_offers_destroy_all	(swarmid: str)	Release all resources and delete all offers for a swarm.
save_capacity_registry_as_yaml	()	Serialize the full capacity registry to YAML string.
load_capacity_registry_from_yaml	(yaml_str)	Load and replace registry state from YAML string.
dump_capacity_registry_info	()	Print registry snapshot via logger.

initialize_capacity_by_content(content: str)

Initializes registry capacity from YAML text content.

• Parameters
  • content: Capacity template as YAML string.
• Behavior
  • Creates a temporary file from the string content and delegates to initialize_capacity_from_file.
• Returns
  • None

Back to API table

initialize_capacity_from_file(filename: str)

Initializes cloud/edge capacity model from a CDT YAML file.

• Parameters
  • filename: Path to the capacity descriptor template.
• Behavior
  • Parses capacities and initializes internal state (free, reserved, assigned, allocated, init) for cloud and/or edge resources.
• Returns
  • None

Back to API table

resource_offer_generate_by_SAT_content(swarmid: str, sat_content: str)

Generates offers for a swarm from SAT YAML text content.

• Parameters
  • swarmid: Swarm identifier.
  • sat_content: Application requirements template as YAML string.
• Behavior
  • Writes SAT content to a temporary file and delegates to resource_offer_generate_from_SAT_file.
• Returns
  • Offer dictionary for the swarm.

Back to API table

resource_offer_generate_from_SAT_file(swarmid: str, sat_filename: str)

Generates placement/resource offers for each microservice in a swarm.

• Parameters
  • swarmid: Swarm identifier.
  • sat_filename: Path to SAT (application requirements) file.
• Behavior
  • Extracts requirements, matches resources, reserves available capacity, and builds offer payloads including IDs and basic characteristics.
  • If none of the matching resources (flavours / edge instances) alone has enough free instances for the required count, the instances are combined from several matching resources into a single mixed offer (offer ID ending with _mixed); each offer instance carries its own res_type/res_id.
  • Stores generated offers under capacity["offers"][swarmid].
• Returns
  • Offer dictionary keyed by microservice ID and offer ID.

Back to API table

resource_offer_query_all(swarmid: str)

Returns all currently stored offers for a swarm.

• Parameters
  • swarmid: Swarm identifier.
• Returns
  • Deep copy of the swarm’s offers (empty dict if missing).

Back to API table

resource_offer_accept(offerid: str, offer: list | dict)

Accepts an offer and moves its resources from reserved to assigned.

• Parameters
  • offerid: Offer ID ("colocated" is treated as a no-op success).
  • offer: Single offer dict or list of offer instances.
• Returns
  • True on success, False if state transition fails.

Back to API table

resource_offer_reject(offerid: str, offer: list | dict)

Rejects an offer, releases reservation, and removes it from offer storage.

• Parameters
  • offerid: Offer ID ("colocated" is treated as a no-op success).
  • offer: Single offer dict or list of offer instances.
• Returns
  • True on success, False if state transition fails.

Back to API table

resource_set_get_from_offer(offerid: str, offer: list | dict)

Extracts a normalized resource-set descriptor from an offer.

• Parameters
  • offerid: Offer ID.
  • offer: Single offer dict or list of offer instances.
• Returns
  • Dict with swarmid, msid, restype, resid, count, or None for colocated placeholder offers. For mixed offers (several resources), a list of such dicts is returned, one per resource.

Back to API table

resource_set_deployed(swarmid: str, msid: str, restype: str, resid: str, count: int)

Marks assigned resources as deployed.

• Parameters
  • swarmid, msid: Swarm and microservice IDs.
  • restype: Resource type (cloud or edge).
  • resid: Resource identifier (flavor/instance name).
  • count: Number of instances.
• Behavior
  • Moves state from assigned to allocated.
• Returns
  • Moved count or None if transition is not possible.

Back to API table

resource_set_undeployed(swarmid: str, msid: str, restype: str, resid: str, count: int)

Marks deployed resources as no longer deployed.

• Parameters
  • Same as resource_set_deployed.
• Behavior
  • Moves state from allocated to assigned.
• Returns
  • Moved count or None if transition is not possible.

Back to API table

resource_set_query_all(swarmid: str, msid: str | None = None)

Returns tracked resource state entries for a swarm (optionally for one MS).

• Parameters
  • swarmid: Swarm identifier.
  • msid: Optional microservice ID.
• Returns
  • Deep copy of resource-state subtree.

Back to API table

resources_and_offers_destroy_all(swarmid: str)

Releases all tracked resources and removes all offers for a swarm.

• Parameters
  • swarmid: Swarm identifier.
• Behavior
  • Moves all non-zero states back to free, then deletes swarm entries from both resource and offer registries.
• Returns
  • True

Back to API table

save_capacity_registry_as_yaml()

Serializes the full in-memory capacity registry to YAML format.

• Returns
  • YAML string representation of self.capacity.

Back to API table

load_capacity_registry_from_yaml(yaml_str)

Loads registry state from a YAML string.

• Parameters
  • yaml_str: YAML document containing a serialized capacity registry.
• Behavior
  • Replaces current in-memory self.capacity with parsed YAML content.
• Returns
  • None

Back to API table

dump_capacity_registry_info()

Prints a human-readable snapshot of cloud/edge capacities and swarm state.

• Returns
  • None (logging output only).

Back to API table

Notes

• swch_capreg/methods.py contains the method-name catalog used for API documentation/discovery.
• AppReq and ResCap are internal helper modules used by SwChCapacityRegistry.

Test scripts overview

The following scripts in tests/ demonstrate end-to-end usage patterns:

• tests/test_cloud_basics_raw.py: Cloud basics using raw cloud capacity (sztaki-capacity-raw.yaml); demonstrates requirement matching, available-instance calculation, and manual state transitions (free -> reserved -> assigned -> allocated).
• tests/test_cloud_basics_flavour.py: Same cloud-basics flow as above, but using flavor-based cloud capacity (sztaki-capacity-flavor.yaml).
• tests/test_cloud_offers_raw.py: Cloud offer lifecycle using raw cloud capacity; demonstrates offer generation from SAT file, querying offers, accept/reject offers, deployment/undeployment transitions, and final cleanup.
• tests/test_cloud_offers_flavour.py: Same cloud offer lifecycle scenario as above, but with flavor-based cloud capacity.
• tests/test_edge_basics.py: Edge basics scenario on edge-capacity.yaml; demonstrates matching edge resources and manual resource-state transitions for edge placements.
• tests/test_edge_offers.py: Edge offer lifecycle scenario; demonstrates CDT-based initialization by in-memory YAML content and SAT loading by in-memory YAML content, offer generation, accept/reject offers, registering deployment/undeployment, resource-set querying, and cleanup.