dictrack package

Subpackages

• dictrack.conditions package
  • Submodules
  • dictrack.conditions.base module
    • BaseCondition
      • BaseCondition.DEFAULT
      • BaseCondition.check()
  • dictrack.conditions.keys module
    • KeyExists
      • KeyExists.check()
      • KeyExists.key
    • KeyNotExists
      • KeyNotExists.check()
    • KeyValueComparison
      • KeyValueComparison.check()
      • KeyValueComparison.op
      • KeyValueComparison.value
    • KeyValueContained
      • KeyValueContained.check()
      • KeyValueContained.value
    • KeyValueEQ
    • KeyValueGE
    • KeyValueGT
    • KeyValueInList
      • KeyValueInList.check()
      • KeyValueInList.value
    • KeyValueLE
    • KeyValueLT
    • KeyValueListHasItem
      • KeyValueListHasItem.check()
      • KeyValueListHasItem.value
    • KeyValueListIntersectList
      • KeyValueListIntersectList.check()
      • KeyValueListIntersectList.value
    • KeyValueListNotHasItem
      • KeyValueListNotHasItem.check()
    • KeyValueListNotIntersectList
      • KeyValueListNotIntersectList.check()
    • KeyValueNE
    • KeyValueNotContained
      • KeyValueNotContained.check()
    • KeyValueNotInList
      • KeyValueNotInList.check()
  • Module contents
• dictrack.data_caches package
  • Submodules
  • dictrack.data_caches.base module
    • BaseDataCache
      • BaseDataCache.cache()
      • BaseDataCache.cache_all()
      • BaseDataCache.fetch()
      • BaseDataCache.flush()
      • BaseDataCache.is_cached()
      • BaseDataCache.remove()
      • BaseDataCache.start_scheduler()
      • BaseDataCache.track()
  • dictrack.data_caches.memory module
  • dictrack.data_caches.redis module
  • Module contents
• dictrack.data_stores package
  • Submodules
  • dictrack.data_stores.base module
    • BaseDataStore
      • BaseDataStore.flush()
      • BaseDataStore.load()
      • BaseDataStore.remove()
      • BaseDataStore.start_scheduler()
      • BaseDataStore.store()
      • BaseDataStore.store_all()
  • dictrack.data_stores.mongodb module
  • Module contents
• dictrack.limiters package
  • Submodules
  • dictrack.limiters.base module
    • BaseLimiter
      • BaseLimiter.post_track()
      • BaseLimiter.pre_track()
      • BaseLimiter.reset()
  • dictrack.limiters.count module
    • CountLimiter
      • CountLimiter.post_track()
      • CountLimiter.reset()
  • dictrack.limiters.time module
    • TimeLimiter
      • TimeLimiter.pre_track()
      • TimeLimiter.reset()
  • Module contents
• dictrack.trackers package
  • Subpackages
    • dictrack.trackers.numerics package
      • Submodules
      • dictrack.trackers.numerics.accumulation module
      • dictrack.trackers.numerics.count module
      • dictrack.trackers.numerics.numeric module
      • Module contents
  • Submodules
  • dictrack.trackers.base module
    • BaseTracker
      • BaseTracker.DEFAULT_GROUP_ID
      • BaseTracker.add_listener()
      • BaseTracker.add_targets()
      • BaseTracker.completed
      • BaseTracker.conditions
      • BaseTracker.current_stage
      • BaseTracker.deserialize()
      • BaseTracker.deserialize_list()
      • BaseTracker.dirtied
      • BaseTracker.forward_event()
      • BaseTracker.group_id
      • BaseTracker.limited
      • BaseTracker.limiters
      • BaseTracker.loop_forever
      • BaseTracker.multi_target
      • BaseTracker.name
      • BaseTracker.progress
      • BaseTracker.removed
      • BaseTracker.reset()
      • BaseTracker.reset_policy
      • BaseTracker.serialize()
      • BaseTracker.target
      • BaseTracker.track()
    • ResetPolicy
      • ResetPolicy.ALL
      • ResetPolicy.DEFAULT
      • ResetPolicy.LIMITER
      • ResetPolicy.NONE
      • ResetPolicy.PROGRESS
  • Module contents
• dictrack.utils package
  • Submodules
  • dictrack.utils.errors module
    • ConflictingNameError
    • DataStoreOperationError
    • GroupIdAlreadySetError
    • GroupIdDuplicateSetError
    • GroupIdLookupError
    • NameLookupError
    • RedisOperationError
    • TrackerAlreadyCompletedError
    • TrackerAlreadyRemovedError
    • TrackerLookupError
  • dictrack.utils.logger module
  • dictrack.utils.utils module
    • numeric()
    • str_to_operator()
    • typecheck()
    • valid_callable()
    • valid_elements_obj()
    • valid_elements_type()
    • valid_obj()
    • valid_type()
  • Module contents

Submodules

dictrack.events module

class dictrack.events.BaseEvent(code)

Bases: object

class dictrack.events.LimitedTrackerEvent(code, group_id, name, tracker, limiter)

Bases: TrackerEvent

class dictrack.events.TrackerEvent(code, group_id, name, tracker)

Bases: BaseEvent

dictrack.manager module

class dictrack.manager.TrackingManager(data_cache, data_store)

Bases: object

add_listener(code, cb)

Add a listener callback for a specific event code.

Parameters:

• code (int) – The event code that the listener will respond to. Must be a valid value within EVENT_ALL.

• cb (callable) – The callback function to execute when the specified event occurs.

Raises:

• ValueError – If code is not within the valid event codes in EVENT_ALL.

• TypeError – If cb is not a callable function or object.

Notes

Multiple listeners can be registered for the same event code, and each will be called when the event is dispatched.

add_tracker(group_id, tracker, expire=None, expire_at=None, **kwargs)

Add a single tracker to a specified group and store it in both cache and data store.

Parameters:

• group_id (str) – The ID of the group to which the tracker belongs.

• tracker (BaseTracker) – The tracker instance to add.

• expire (int, optional) – Expiration time for the tracker in seconds. Defaults to None.

• expire_at (int, optional) – Specific expiration timestamp for the tracker. Defaults to None.

• **kwargs (dict) – Additional keyword arguments for customization.

Raises:

TypeError – If expire or expire_at is not an integer or None.

Notes

Dispatches a TrackerEvent with EVENT_TRACKER_ADDED after adding the tracker.

add_trackers(group_id, trackers, expire=None, expire_at=None, **kwargs)

Add multiple trackers to a specified group and store them in both cache and data store.

Parameters:

• group_id (str) – The ID of the group to which the trackers belongs.

• trackers (list of BaseTracker) – List of tracker instances to add.

• expire (int, optional) – Expiration time for the trackers in seconds. Defaults to None.

• expire_at (int, optional) – Specific expiration timestamp for the trackers. Defaults to None.

• **kwargs (dict) – Additional keyword arguments for customization.

Raises:

TypeError – If any tracker in trackers is not an instance of BaseTracker, or if expire or expire_at are not integers.

Notes

Dispatches a TrackerEvent with EVENT_TRACKER_ADDED for each tracker after adding.

flush(confirm=False)

Clear all cached and stored data permanently.

Parameters:

confirm (bool, optional) – Confirmation flag to execute flush. Must be True to proceed. Defaults to False.

Return type:

None

Notes

This action is irreversible and will remove all data from both cache and data store.

get_trackers(group_id, name=None)

Retrieve tracker(s) by group ID and optional tracker name(s).

Parameters:

• group_id (str) – The ID of the group from which to retrieve trackers.

• name (str or list of str, optional) – Name(s) of specific trackers to retrieve. If None, retrieves all trackers in the group. Defaults to None.

Returns:

List of retrieved tracker instances. Returns an empty list if retrieval fails.

Return type:

list of BaseTracker

Raises:

TypeError – If name is not a string, list, or None.

remove_tracker(group_id, name=None)

Remove a tracker or multiple trackers from both the cache and data store.

Parameters:

• group_id (str) – The ID of the group from which to remove the tracker(s).

• name (str or list of str, optional) – Name(s) of specific trackers to remove. If None, removes all trackers in the group. Defaults to None.

Raises:

TypeError – If name is not a string, list, or None.

reset_tracker(group_id, name, reset_policy=None, *args, **kwargs)

Reset a tracker in a specified group according to the provided reset policy.

Parameters:

• group_id (str) – The ID of the group to which the tracker belongs.

• name (str) – The name of the tracker to reset.

• reset_policy (int, optional) – The reset policy to apply, controlling which aspects of the tracker to reset. Must be a valid value within the ResetPolicy range. Defaults to None, using the tracker’s default policy. Supports bitwise combination using | to apply multiple reset policies simultaneously (e.g., ResetPolicy.PROGRESS | ResetPolicy.LIMITER).

Returns:

True if the tracker was found and reset successfully; False if the tracker was not found.

Return type:

bool

Raises:

TypeError – If name is not a string or if reset_policy is not a valid integer within ResetPolicy range.

Notes

Dispatches reset events through the tracker’s forward_event method and updates the tracker after reset.

track(group_id, data, **kwargs)

Tracking for a specified group, updating cached trackers with provided data.

Parameters:

• group_id (str) – The ID of the group for which to track the event.

• data (dict) – The data associated with the event to be tracked.

• **kwargs (dict) – Additional keyword arguments for customization.

Returns:

A tuple containing: - bool: True if tracking was successful; False if loading trackers failed. - list of BaseTracker: Trackers that were modified (dirtied) during tracking. - list of BaseTracker: Trackers that were completed during tracking. - list of BaseTracker: Trackers that hit a limit during tracking.

Return type:

tuple

Notes

If the group is not already cached, trackers are loaded from the data store and cached before tracking.

update_tracker(group_id, tracker)

Update a tracker in both the cache and data store. If the tracker is already cached, it will be updated in the cache with force=True. Otherwise, it is stored directly in the data store.

Parameters:

• group_id (str) – The ID of the group to which the tracker belongs.

• tracker (BaseTracker) – The tracker instance to be updated.

Raises:

TypeError – If tracker is not an instance of BaseTracker.

Module contents