rattail.batch.handlers

Data Batch Handlers

class rattail.batch.handlers.BatchHandler(config)[source]

Base class and partial default implementation for batch handlers. It is expected that all batch handlers will ultimately inherit from this base class, therefore it defines the implementation “interface” loosely speaking. Custom batch handlers are welcome to supplement or override this as needed, and in fact must do so for certain aspects.

populate_batches

Simple flag to indicate whether any/all batches being handled, will require initial population from a relevant data source. Note that this flag should be set to True if any batches may need population. Whether or not a given batch actually needs to be populated, is ultimately determined by the should_populate() method.

populate_with_versioning

This flag indicates whether it’s okay for data versioning to be enabled during initial batch population.

If set to True (the default), then versioning is allowed and therefore the caller need take no special precautions when populating the batch.

If set to False then versioning is not allowed; if versioning is not enabled for the current process, the caller may populate the batch with no special precautions. However if versioning is enabled, the caller must launch a separate process with versioning disabled, in order to populate the batch.

refresh_with_versioning

This flag indicates whether it’s okay for data versioning to be enabled during batch refresh.

If set to True (the default), then versioning is allowed and therefore the caller need take no special precautions when populating the batch.

If set to False then versioning is not allowed; if versioning is not enabled for the current process, the caller may populate the batch with no special precautions. However if versioning is enabled, the caller must launch a separate process with versioning disabled, in order to refresh the batch.

execute_with_versioning

This flag indicates whether it’s okay for data versioning to be enabled during batch execution.

If set to True (the default), then versioning is allowed and therefore the caller need take no special precautions when populating the batch.

If set to False then versioning is not allowed; if versioning is not enabled for the current process, the caller may populate the batch with no special precautions. However if versioning is enabled, the caller must launch a separate process with versioning disabled, in order to execute the batch.

repopulate_when_refresh

Flag to indicate that when a batch is refreshed, the first step of that should be to re-populate the batch. The flag is False by default, in which case the batch is not repopulated, i.e. the refresh will work with existing batch rows.

batch_key

The “batch type key” for the handler, e.g. 'labels'. This isn’t necessarily unique among handlers, but instead refers to a unique key for the type of batch being handled. The handler needn’t define this, as it is borrowed from batch_model_class.

batch_model_class

Reference to the data model class of the batch type for which this handler is responsible, e.g. rattail.db.model.LabelBatch. Each handler must define this (or inherit from one that does).

executable(batch)[source]

This method should return a boolean indicating whether or not execution should be allowed for the batch, given its current condition. The default simply returns True but you may override as needed.

Note that this (currently) only affects the enabled/disabled state of the Execute button within the Tailbone batch view.

execute(batch, progress=None, **kwargs)[source]

Execute the given batch, with given progress and kwargs. That is an intentionally generic statement, the meaning of which must be further defined by the handler subclass since default is NotImplementedError.

Note that callers should not use this method, but custom batch handlers should override this method. Conversely, custom handlers should not override the do_execute() method, but callers should use that one directly.

make_batch(session, progress=None, **kwargs)[source]

Make a new batch, with initial rows if applicable.

populate(batch, progress=None)[source]

Populate the batch with initial data rows. It is assumed that the data source to be used will be known by inspecting various properties of the batch itself.

Note that callers should not use this method, but custom batch handlers should override this method. Conversely, custom handlers should not override the do_populate() method, but callers should use that one directly.

refresh(batch, progress=None)[source]

Perform a full data refresh for the batch. What exactly this means will depend on the type of batch, and specific handler logic.

Generally speaking this refresh is meant to use queries etc. to obtain “fresh” data for the batch (header) and all its rows. In most cases certain data is expected to be “core” to the batch and/or rows, and such data will be left intact, with all other data values being re-calculated and/or reset etc.

refresh_row(row)[source]

This method will be passed a row object which has already been properly added to a batch, and which has basic required fields already populated. This method is then responsible for further populating all applicable fields for the row, based on current data within the relevant system(s).

Note that in some cases this method may be called multiple times for the same row, e.g. once when first creating the batch and then later when a user explicitly refreshes the batch. The method logic must account for this possibility.

refreshable(batch)[source]

This method should return a boolean indicating whether or not the handler supports a “refresh” operation for the batch, given its current condition. The default assumes a refresh is allowed unless the batch is executed.

Note that this (currently) only affects the enabled/disabled state of the Refresh button within the Tailbone batch view.

should_populate(batch)[source]

Must return a boolean indicating whether the given batch should be populated from an initial data source, i.e. at time of batch creation. Override this method if you need to inspect the batch in order to determine whether the populate step is needed. Default behavior is to simply return the value of populate_batches.

setup_populate(batch, progress=None)[source]

Perform any setup (caching etc.) necessary for populating a batch.

setup_refresh(batch, progress=None)[source]

Perform any setup (caching etc.) necessary for refreshing a batch.

teardown_populate(batch, progress=None)[source]

Perform any teardown (cleanup etc.) necessary after populating a batch.

teardown_refresh(batch, progress=None)[source]

Perform any teardown (cleanup etc.) necessary after refreshing a batch.

rattail.batch.handlers.get_batch_handler(config, batch_key, default=None, error=True)[source]

Returns a batch handler object corresponding to the given batch key.