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
Links
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_link_examples()
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.