Priority API

Priority Tree

class priority.PriorityTree(maximum_streams: int = 1000)[source]

A HTTP/2 Priority Tree.

This tree stores HTTP/2 streams according to their HTTP/2 priorities.

Changed in version 1.2.0: Added maximum_streams keyword argument.

Parameters:

maximum_streams (int) –

The maximum number of streams that may be active in the priority tree at any one time. If this number is exceeded, the priority tree will raise a TooManyStreamsError and will refuse to insert the stream.

This parameter exists to defend against the possibility of DoS attack by attempting to overfill the priority tree. If any endpoint is attempting to manage the priority of this many streams at once it is probably trying to screw with you, so it is sensible to simply refuse to play ball at that point.

While we allow the user to configure this, we don’t really expect them too, unless they want to be even more conservative than we are by default.

block(stream_id: int) → None[source]

Marks a given stream as blocked, with no data to send.

Parameters:

stream_id – The ID of the stream to block.

insert_stream(stream_id: int, depends_on: int | None = None, weight: int = 16, exclusive: bool = False) → None[source]

Insert a stream into the tree.

Parameters:

  • stream_id – The stream ID of the stream being inserted.

  • depends_on – (optional) The ID of the stream that the new stream depends on, if any.

  • weight – (optional) The weight to give the new stream. Defaults to 16.

  • exclusive – (optional) Whether this new stream should be an exclusive dependency of the parent.

remove_stream(stream_id: int) → None[source]

Removes a stream from the priority tree.

Parameters:

stream_id – The ID of the stream to remove.

reprioritize(stream_id: int, depends_on: int | None = None, weight: int = 16, exclusive: bool = False) → None[source]

Update the priority status of a stream already in the tree.

Parameters:

  • stream_id – The stream ID of the stream being updated.

  • depends_on – (optional) The ID of the stream that the stream now depends on. If None, will be moved to depend on stream 0.

  • weight – (optional) The new weight to give the stream. Defaults to 16.

  • exclusive – (optional) Whether this stream should now be an exclusive dependency of the new parent.

unblock(stream_id: int) → None[source]

Marks a given stream as unblocked, with more data to send.

Parameters:

stream_id – The ID of the stream to unblock.

Exceptions

class priority.PriorityError[source]

The base class for all priority exceptions.

class priority.DeadlockError[source]

Raised when there are no streams that can make progress: all streams are blocked.

class priority.PriorityLoop[source]

An unexpected priority loop has been detected. The tree is invalid.

class priority.DuplicateStreamError[source]

An attempt was made to insert a stream that already exists.

class priority.MissingStreamError[source]

An operation was attempted on a stream that is not present in the tree.

class priority.TooManyStreamsError[source]

An attempt was made to insert a dangerous number of streams into the priority tree at the same time.

New in version 1.2.0.

class priority.BadWeightError[source]

An attempt was made to create a stream with an invalid weight.

New in version 1.3.0.

class priority.PseudoStreamError[source]

An operation was attempted on stream 0.

New in version 1.3.0.