kilter.service.options module

Filter decorators for marking the requested protocol options and actions used

class CanRespond(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Flag

Flags for fine indication of which stages during message sending a filter may respond at

Used with examine_headers() and examine_body() to further refine which stages during message header and body transfer will synchronously block until a response of some kind is received.

NEVER = 0

BEFORE = 1

DURING = 2

AFTER = 4

ALL = 7

responds_to_connect() → Callable[[Filter], Filter]

Mark a filter as possibly delivering a non-continue response to Connect events

examine_helo(can_respond: bool = False) → Callable[[Filter], Filter]

Mark a filter as needing to examine the HELO command

If can_respond is False the filter runner will attempt to negotiate faster event delivery by disabling the need to respond to this event.

examine_sender(can_respond: bool = False, can_replace: bool = False) → Callable[[Filter], Filter]

Mark a filter as needing to examine and optionally replace the RCPT FROM sender

If can_respond is False the filter runner will attempt to negotiate faster event delivery by disabling the need to respond to this event.

If can_replace is True but is not offered by the MTA an exception will be raised during negotiation and the filter will be disabled.

examine_recipients(can_respond: bool = False, can_add: bool = False, can_remove: bool = False, include_rejected: bool = False, with_parameters: bool = False) → Callable[[Filter], Filter]

Mark a filter as needing to examine and optionally modify the RCPT TO recipients

If can_respond is False the filter runner will attempt to negotiate faster event delivery by disabling the need to respond to this event.

If include_rejected is True the recipients available to the filter will include any that the MTA or another filter has already rejected.

The option with_parameters enables the use of RFC-1425 [section 6] extensions for “MAIL” commands (ratified by RFC-5321) when adding recipients. The specific details of any extension parameters will be dependent on the MTA.

If a requested option or update action is not offered by the MTA an exception will be raised during negotiation and the filter will be disabled.

examine_headers(can_respond: bool | kilter.service.options.CanRespond = False, can_add: bool = False, can_modify: bool = False, leading_space: bool = False) → Callable[[Filter], Filter]

Mark a filter as needing to examine and optionally add or modify message headers

If can_respond is False the filter runner will attempt to negotiate faster event delivery by disabling the need to respond to this event.

If leading_space is True the headers will be delivered without any whitespace removed from values (i.e. after the separating colon). This is for filters which need the exact bytes contained in message headers.

If a requested option or update action is not offered by the MTA an exception will be raised during negotiation and the filter will be disabled.

examine_body(can_respond: bool | kilter.service.options.CanRespond = False, can_replace: bool = False, data_size: ~typing.Literal[<ProtocolFlags.NONE: 0>, <ProtocolFlags.MAX_DATA_SIZE_256K: 268435456>, <ProtocolFlags.MAX_DATA_SIZE_1M: 536870912>] = ProtocolFlags.NONE) → Callable[[Filter], Filter]

Mark a filter as needing to examine and optionally replace message bodies

If can_respond is False the filter runner will attempt to negotiate faster event delivery by disabling the need to respond to this event.

The data_size option is a hint, and does not guarantee that the message will be delivered in blocks of that size. If ProtocolFlags.NONE (the default) the MTA’s default will be used.

If can_replace is True but is not offered by the MTA an exception will be raised during negotiation and the filter will be disabled.

get_flags(filtr: Filter) → FlagsTuple

Return the flags attached to a filter

modify_flags(set_options: ProtocolFlags = ProtocolFlags.NONE, unset_options: ProtocolFlags = ProtocolFlags.NONE, set_actions: ActionFlags = ActionFlags.NONE) → Callable[[Filter], Filter]

Return a decorator that modifies the given flags on a decorated filter

get_macros(filtr: Filter) → defaultdict[Stage, set[str]]

Return the requested macros attached to a filter

request_macros(stage: Stage, *names: str) → Callable[[Filter], Filter]

Return a decorator that adds the given macro requests to a decorated filter