Skip to content

Vultron ActivityStreams Vocabulary Base Package

vultron.wire.as2.vocab.base

Provides an implementation of the ActivityStreams 2.0 protocol.

vultron.wire.as2.vocab.base.base

This module provides a base class for Vultron Activity Stream classes.

PropertyValueKind

Bases: StrEnum

The shape of a Vultron property's value (VM-10-008, VM-10-010).

The context generator types the property's JSON-LD term from it, as the AS2 context types its own terms (ADR-0194). A scalar kind says what one value is; a container kind says how an array or map of values is read, and its declaration's items says what each value in it is.

as_Base

Bases: BaseModel

Root of the wire vocabulary for AS2 types that have no core class.

Under ARCH-25-004 (ADR-0099) this root inherits nothing from core: the core classes are the object model and AS2 is their serialization, so there is no shared ancestor to keep lenient for both. What remains here is unpaired AS2 vocabulary (as_Link, the generic activities) and it declares its own fields and configuration.

carry_absent_times_on_inbound(data, info) classmethod

Refuse a received whole object with no published, and read any other absent timestamp as None, when inbound.

The same classes author outbound activities and validate inbound ones. An authored object states its time (ADR-0176). A received whole object carries its author's published, and one without it is refused with MissingClaimedTimeError unless its kind is exempt or it is a typed reference (CLP-15-011, MV-10-011). Any other time it omits, such as updated, is the sender claiming none, never the receiver's clock presented as the sender's claim (ISSUE-3257, CLP-15-007). The two directions are told apart by validation context rather than by a field default: parse_activity passes INBOUND_CONTEXT_KEY, and Pydantic propagates the context through every nested model in that call.

Doing this here rather than in the parser is what makes the rule hold at every depth. The parser can only pre-treat a dict whose type it resolved; an inline object that omits type stays a raw dict for the parent field to validate, and that validation lands here, on the class the field actually chose. Each class sees only its own model_fields, so a class without timestamps (as_Link) is untouched rather than handed a key it would refuse.

The minted id default is the same fabrication, so it is gated the same way: a received Object without an id is refused, and a received Link (_inbound_requires_id false) that omits one keeps none (OID-01-013, OID-01-014).

from_json(data) classmethod

Deserialize a JSON string to an instance of the model.

narrow_received_type_list(data) classmethod

Read a type list as the one term it resolves to (ADR-0196).

type_ holds one string, so the list an extension class serializes (_as2_core_supertype), or any list a peer sends, is narrowed to the term of its most specific known class before the field validates it. A class whose own declared type is in the list reads it as that type: a list names each of its terms, so as_Reject reads ["Refuse", "Reject"] as a Reject, and a subclass that inherits type_ reads it the same way. A list that names no wire type is read as the core-only type it names (VM-06-008), else as its first term, as a string naming no known type is kept (an unknown inline object stays an as_Object, MV-04-004, VM-03-006). A list of two unrelated known types, or one with no string term, is refused.

to_dict(**kwargs)

Serialize the model to a dictionary, excluding None values and using aliases.

to_json(**kwargs)

Serialize the model to a JSON string, excluding None values and using aliases.

vultron_property(definition, kind, *, items=PropertyValueKind.PLAIN)

The marker that declares a field a Vultron property: pass it as the field's json_schema_extra (VM-10-007, VM-10-008).

definition is the property's meaning in one line; kind is its value's shape, and items, for a container kind, the shape of each value in it. Raises ValueError (a pydantic.ValidationError) on a declaration :class:VultronPropertyDeclaration refuses.

Objects

Activities

Utilities

vultron.wire.as2.vocab.base.utils

Provides utilities for the ActivityStreams Vocabulary.

generate_new_id = new_object_id module-attribute

The wire layer's id_ default factory: the shared core minter itself.

The wire layer mints no ids of its own (OID-01-004). The name stays because it is the as_Base.id_ default factory (VM-04-001); it is the same function as :func:vultron.core.models._helpers.new_object_id, prefix form included.

exclude_if_none(value)

Exclude a field if it is None

Parameters:

Name Type Description Default
value Any

The value to check

required

Returns:

Type Description
bool

True if the value is None, False otherwise

is_blank(value)

Return True when value carries no content: absent, null, or blank.

A required field that is present but empty carries nothing, so it is absence rather than a malformed value — CS-08-001's "if present, then non-empty". Whitespace-only counts as blank: the string case is decided by the project's canonical predicate, vultron.primitives.is_blank_string, which NonEmptyString and require_non_empty also use.

Deliberately narrower than a bare falsy test: 0, [] and {} are malformed values for the fields this guards, not omitted ones, and reporting them as missing would tell the sender to supply a field they already sent (ISSUE-3217).

This is the single definition of "blank" for the wire layer. Both parser.parse_activity's required-field guards and the shared timestamp validator in vocab.base.objects.base read it from here, so the two cannot drift apart (CS-22-001).

Parameters:

Name Type Description Default
value Any

The value to check

required

Returns:

Type Description
bool

True if the value is absent, None, or a whitespace-only string

name_of(obj)

Return a concise human-readable label for an AS2 object or reference.

Resolution order: 1. Strings are returned unchanged (already a URI or label). 2. obj.name if present and not None. 3. obj.href if present and not None (AS2 Link objects). 4. obj.id_ if present and not None (any AS2/domain object). 5. str(obj) as a last resort.

Parameters:

Name Type Description Default
obj Any

The object to get the name of — may be a string, an AS2 object, an AS2 Link, or any other value.

required

Returns:

Type Description
str

A short, human-readable string representation of obj.

print_activity_examples()

Print out empty examples of the classes in the given module

Print out empty examples of the classes in the given module

print_object_examples()

Print out empty examples of the classes in the given module

Errors

vultron.wire.as2.vocab.base.errors

This module provides custom errors

ActivityVocabularyError

Bases: VultronError

Base class for all ActivityPub as_vocab errors.

DeserializationError

Bases: ActivityVocabularyError

Raised when a JSON object cannot be deserialized.

IsoDecodingError

Bases: DeserializationError

Raised when an ISO decoding is not recognized.

IsoEncodingError

Bases: SerializationError

Raised when an ISO encoding is not recognized.

MissingTypeError

Bases: DeserializationError

Raised when a type is missing from a JSON object.

SerializationError

Bases: ActivityVocabularyError

Raised when a JSON object cannot be serialized.

UnrecognizedTypeError

Bases: DeserializationError

Raised when an unknown type is encountered.

vultron.wire.as2.vocab.base.objects.errors

This module provides custom errors

ActivityVocabularyObjectError

Bases: ActivityVocabularyError

Base class for all ActivityPub object errors.

vultron.wire.as2.vocab.base.objects.activities.errors

This module provides custom errors

ActivityVocabularyActivityError

Bases: ActivityVocabularyObjectError

Base class for all ActivityPub activity errors.