Reference¶

admin.py¶

Admin configuration for django_segments.

apps.py¶

App configuration.

class django_segments.apps.DjangoSegmentsConfig(app_name, app_module)¶: App configuration for django-segments.

app_settings.py¶

Package settings.

django_segments.apps.DJANGO_SEGMENTS_MODEL_BASE¶: Base model for all segment and span models. Default is django.db.models.base.ModelBase. There should be no need to change this, but it is provided for advanced users.

django_segments.apps.POSTGRES_RANGE_FIELDS¶

Dictionary of model range fields and the associated Python types that should be used to represent a boundary value, a delta value, and a range. Default is:

{
    IntegerRangeField: {
        "value_type": int,
        "delta_type": int,
        "range_type": NumericRange,
    },
    BigIntegerRangeField: {
        "value_type": int,
        "delta_type": int,
        "range_type": NumericRange,
    },
    DecimalRangeField: {
        "value_type": Decimal,
        "delta_type": Decimal,
        "range_type": NumericRange,
    },
    DateRangeField: {
        "value_type": date,
        "delta_type": timezone.timedelta,
        "range_type": DateRange,
    },
    DateTimeRangeField: {
        "value_type": datetime,
        "delta_type": timezone.timedelta,
        "range_type": DateTimeTZRange,
    }
}

This is used to convert the range field to a Python type, and for validation when creating a new Span or Segment.

django_segments.apps.DEFAULT_RELATED_NAME¶: Default related name for the Span and Segment models. Default is %(app_label)s_%(class)s_related.

django_segments.apps.DEFAULT_RELATED_QUERY_NAME¶: Default related query name for the Span and Segment models. Default is %(app_label)s_%(class)ss.

Global Span Configuration Options¶

These options are used to configure the behavior of all Span models, and can be overridden on a per-model basis by adding a SpanConfig class with one or more of the corresponding setting names in lowercase to the span model. Example:

class MySpan(AbstractSpan):

    class SpanConfig:
        """Custom configuration options for this span."""

        allow_span_gaps = False
        allow_segment_gaps = False
        soft_delete = False

django_segments.apps.ALLOW_SPAN_GAPS¶: Allow gaps between the boundaries of the Span and its first and last Segments. Default is True. If False, when a new Span is created, a Segment will be created to fill the range of the Span.

django_segments.apps.ALLOW_SEGMENT_GAPS¶: Allow gaps between the Segments in a Span. Default is True. If False, all Segments in a Span must be contiguous.

django_segments.apps.SOFT_DELETE¶: Use soft delete for segments and spans. Default is True. If True, a deleted_at field will be added to the Span and Segment models. When a soft delete occurs, the deleted_at field will be set to the current date and time, and queries will exclude deleted Segments and Spans by default.

Global Segment Configuration Options¶

These options are used to configure the behavior of all Segment models, and can be overridden on a per-model basis by adding a SegmentConfig class with one or more of the corresponding setting names in lowercase to the segment model. Example:

class MySegment(AbstractSegment):

    class SegmentConfig:
        """Custom configuration options for this segment."""

        previous_field_on_delete = models.CASCADE
        span_on_delete = models.CASCADE

django_segments.apps.PREVIOUS_FIELD_ON_DELETE¶: The behavior to use when deleting a segment that has a previous segment. Default is django.db.models.CASCADE.

django_segments.apps.SPAN_ON_DELETE¶: The behavior to use for segment instances with foreign key to a deleted span. Default is django.db.models.CASCADE.

exceptions.py¶

Exceptions for the django_segments package.

exception django_segments.exceptions.IncorrectRangeTypeError¶: Raised when the range type is not one of the supported types specified in the settings.

exception django_segments.exceptions.IncorrectSegmentRangeError¶: Raised when a segment model’s range field is not correctly implemented.

exception django_segments.exceptions.IncorrectSpanRangeError¶: Raised when a span model’s range fields are not correctly implemented.

exception django_segments.exceptions.IncorrectSubclassError¶: Raised when a subclass of BaseSegment is not correctly implemented.

exception django_segments.exceptions.InvalidRangeFieldNameError¶: Raised when the field specified by range_field_name does not exist on the model.

exception django_segments.exceptions.SegmentRelationshipError¶: Raised when the segment instances for a span are not related correctly by previous_segment.

forms.py¶

Forms for django_segments.

models/base.py¶

Base classes and metaclasses for AbstractSpan and AbstractSegment models.

class django_segments.models.base.BaseSegmentMetaclass(name, bases, attrs, **kwargs)¶: Metaclass for AbstractSegment.

class django_segments.models.base.BaseSpanMetaclass(name, bases, attrs, **kwargs)¶: Metaclass for AbstractSpan.

class django_segments.models.base.ConcreteModelValidationHelper¶

Helper class for validating that models are concrete.

static check_model_is_concrete(model)¶

Check that the model is not abstract.

Parameters:: model (Union[AbstractSpan, AbstractSegment])
Return type:: None

class django_segments.models.base.SegmentConfigurationHelper¶

Helper class for retrieving Segment model configurations.

static get_config_attr(model, attr_name, default)¶

Given an attribute name and default value, returns the attribute value from the SegmentConfig class.

Parameters:: attr_name (str)

static get_config_dict(model)¶

Return a dictionary of configuration options.

Parameters:: model (AbstractSegment)
Return type:: dict

static get_span_model(model)¶

Return the span model for the segment model.

Parameters:: model (AbstractSegment)
Return type:: AbstractSpan

class django_segments.models.base.SpanConfigurationHelper¶

Helper class for retrieving Span model configurations.

static get_config_attr(model, attr_name, default)¶

Given an attribute name and default value, returns the attribute value from the SpanConfig class.

Parameters:: attr_name (str)

static get_config_dict(model)¶

Return the configuration options for the span as a dictionary.

Parameters:: model (AbstractSpan)
Return type:: dict

static get_range_field_type(model)¶

Return the range field type for the span model after performing some validation.

Parameters:: model (AbstractSpan)
Return type:: Range

static get_segment_class(model_instance)¶

Get the segment class associated with the span model.

The Segment model has a span ForeignKey field that points to the span model. This method returns the Segment model that is associated with the span model.

Parameters:: model_instance (AbstractSpan)
Return type:: AbstractSegment

django_segments.models.base.boundary_helper_factory(range_field_name)¶

Factory function to create model methods for setting boundaries on a given range field.

Parameters:: range_field_name (str) – The name of the range field.
Returns:: A tuple containing the set_boundaries, set_lower_boundary, and set_upper_boundary methods.
Return type:: tuple

django_segments.models.base.generate_short_hash(name, salt='', length=8)¶

Generate a hash for the given name string.

Parameters:

name (str)
salt (str)
length (int)

Return type:

str

class django_segments.models.base.BaseSpanMetaclass(name, bases, attrs, **kwargs)

Metaclass for AbstractSpan.

static __new__(cls, name, bases, attrs, **kwargs)

Performs actions that need to take place when a new span model is created.

Validates subclass of AbstractSpan & sets initial_range and current_range for the model.

class django_segments.models.base.BaseSegmentMetaclass(name, bases, attrs, **kwargs)

Metaclass for AbstractSegment.

static __new__(cls, name, bases, attrs, **kwargs)

Performs actions that need to take place when a new segment model is created.

Validates subclass of AbstractSegment & sets segment_range and span for the concrete model.

models/segment.py¶

This module contains the AbstractSegment class, which is the base class for all Segment models.

class django_segments.models.segment.AbstractSegment(*args, **kwargs)¶

Abstract class from which all Segment models should inherit.

All concrete subclasses of AbstractSegment must define a SegmentConfig class, with at minimum a span_model (as a subclass of AbstractSpan). If not defined, an IncorrectSubclassError will be raised.

Examples:

class MySegment(AbstractSegment):
    span_model = MySpan

    previous_field_on_delete = models.SET_NULL  # Overriding a global setting

class MyOtherSegment(AbstractSegment):
    span_model = MyOtherSpan

class SegmentConfig¶: Configuration options for the segment.

append(to_value=None, delta_value=None, **kwargs)¶

Append a Segment to using the given value or delta value.

Parameters:

to_value (int | Decimal | date | datetime | Range | None)
delta_value (int | Decimal | timedelta | None)

Return type:

None

delete()¶: Delete the Segment.

property first¶: Return the first segment in the span.

insert(*, span, segment_range)¶

Insert a new segment into the span.

Parameters:

span (Model)
segment_range (Range | DateRange | DateTimeTZRange | NumericRange)

property is_active¶: Return True if the segment is not deleted.

property is_deleted¶: Return True if the segment is deleted.

property is_first¶: Return True if the segment is the first segment in the span.

property is_first_and_last¶: Return True if the segment is the first and last segment in the span.

property is_first_or_last¶: Return True if the segment is the first and last segment in the span.

property is_internal¶: Return True if the segment is not the first or last segment in the span.

property is_last¶: Return True if the segment is the last segment in the span.

property last¶: Return the last segment in the span.

merge_into_lower()¶: Merge the segment into the previous (lower) segment.

merge_into_upper()¶: Merge the segment into the next (upper) segment.

property next¶: Return the next segment.

property previous¶: Return the previous segment.

shift_by_value(delta_value)¶: Shift the range value of the entire Segment.

shift_lower_by_value(delta_value)¶: Shift the lower boundary of the Segment’s segment_range by the given value.

shift_lower_to_value(to_value)¶

Shift the lower boundary of the Segment’s segment_range to the given value.

Parameters:: to_value (int | Decimal | datetime | date)
Return type:: None

shift_upper_by_value(delta_value)¶: Shift the upper boundary of the Segment’s segment_range by the given value.

shift_upper_to_value(to_value)¶

Shift the upper boundary of the Segment’s segment_range to the given value.

Parameters:: to_value (int | Decimal | datetime | date)
Return type:: None

split(split_value, fields_to_copy=None)¶: Split the segment into two at the provided value.

class django_segments.models.segment.SegmentManager(*args, **kwargs)¶

Custom Manager for Segment models.

Models inheriting from AbstractSegment will have access to this custom Manager. For custom methods, use this Manager as a base class and add your custom methods.

create(span, segment_range, **kwargs)¶: Uses the Segment’s create method to create a new Segment instance.

get_queryset()¶: Return a custom queryset.

class django_segments.models.segment.SegmentQuerySet(model=None, query=None, using=None, hints=None)¶

Custom QuerySet for Segment models.

Models inheriting from AbstractSegment will have access to this custom QuerySet. For custom methods, use this QuerySet as a base class and add your custom methods.

active()¶: Return only active segments.

deleted()¶: Return only deleted segments.

models/span.py¶

This module contains the AbstractSpan class, which is the base class for all Span models.

class django_segments.models.span.AbstractSpan(*args, **kwargs)¶

Abstract class from which all Span models should inherit.

All concrete subclasses of AbstractSpan must define a SpanConfig class, with at minimum a range_field_type. If not defined, an IncorrectRangeTypeError will be raised.

Example:

class MySpan(AbstractSpan):
    class SpanConfig:
        range_field_type = DateTimeRangeField

        allow_span_gaps = False  # Overriding a global setting

class SpanConfig¶: Configuration options for the span.

append(to_value=None, delta_value=None, **kwargs)¶

Append a new Segment to the Span using the given value or delta value.

Parameters:

to_value (int | Decimal | date | datetime | Range | None)
delta_value (int | Decimal | timedelta | None)

Return type:

None

delete()¶

Delete the Span and its associated Segments.

Return type:: None

property first_segment¶: Return the first segment associated with the span.

get_active_segments()¶

Return all active segments associated with the span.

Return type:: QuerySet

get_inactive_segments()¶

Return all inactive segments associated with the span.

Return type:: QuerySet

get_segments()¶

Return all segments associated with the span.

Return type:: QuerySet

property last_segment¶: Return the last segment associated with the span.

property segment_count: int¶: Return the number of segments associated with the span.

shift_by_value(delta_value)¶

Shift the range value of the entire Span and each of its associated Segments by the given value.

Parameters:: delta_value (int | Decimal | timedelta)
Return type:: None

shift_lower_by_value(delta_value)¶

Shift the lower boundary of the Span’s current_range by the given value.

Parameters:: delta_value (int | Decimal | timedelta)
Return type:: None

shift_lower_to_value(to_value)¶

Shift the lower boundary of the Span’s current_range to the given value.

Parameters:: to_value (int | Decimal | datetime | date)
Return type:: None

shift_upper_by_value(delta_value)¶

Shift the upper boundary of the Span’s current_range by the given value.

Parameters:: delta_value (int | Decimal | timedelta)
Return type:: None

shift_upper_to_value(to_value)¶

Shift the upper boundary of the Span’s current_range to the given value.

Parameters:: to_value (int | Decimal | datetime | date)
Return type:: None

class django_segments.models.span.SpanManager(*args, **kwargs)¶

Custom Manager for Span models.

Models inheriting from AbstractSpan will have access to this custom Manager. For custom methods, use this Manager as a base class and add your custom methods.

get_queryset()¶: Return the custom QuerySet for Span models.

class django_segments.models.span.SpanQuerySet(model=None, query=None, using=None, hints=None)¶

Custom QuerySet for Span models.

Models inheriting from AbstractSpan will have access to this custom QuerySet. For custom methods, use this QuerySet as a base class and add your custom methods.

active()¶: Return only active spans.

deleted()¶: Return only deleted spans.

signals.py¶

Signals for the django_segments app.

Create

span_pre_create: Sent before a span is created.
segment_pre_create: Sent before a segment is created.
span_post_create: Sent after a span is created.
segment_post_create: Sent after a segment is created.

Pre Delete

segment_pre_delete: Sent before a segment is deleted.
segment_pre_soft_delete: Sent before a segment is soft deleted.
segment_pre_delete_or_soft_delete: Sent before a segment is deleted or soft deleted.
span_pre_delete: Sent before a span is deleted.
span_pre_soft_delete: Sent before a span is soft deleted.
span_pre_delete_or_soft_delete: Sent before a span is deleted or soft deleted.

Post Delete

segment_post_delete: Sent after a segment is deleted.
segment_post_soft_delete: Sent after a segment is soft deleted.
segment_post_delete_or_soft_delete: Sent after a segment is deleted or soft deleted.
span_post_delete: Sent after a span is deleted.
span_post_soft_delete: Sent after a span is soft deleted.
span_post_delete_or_soft_delete: Sent after a span is deleted or soft deleted.

Update

segment_pre_update: Sent before a segment is updated.
segment_post_update: Sent after a segment is updated.
span_pre_update: Sent before a span is updated.
span_post_update: Sent after a span is updated.

When deleting or soft deleting a span, several signals are sent as the Span and its associated Segments are deleted. In each case, the more specific signal is wrapped in the more general signal. This allows you to connect to the more general signal and still receive the more specific signal. The signals are sent in the following order:

views.py¶

Views for django_segments.

urls.py¶

URLs for django_segments.