recordtransfer.models - Data Models

class recordtransfer.models.User(*args, **kwargs)

The main User object used to authenticate users.

property full_name: str: Return the full name of the user, which is a combination of first and last names.

property has_contact_info: bool: Check if user has complete contact information.

exception DoesNotExist

exception MultipleObjectsReturned

class recordtransfer.models.SiteSetting(*args, **kwargs)

A model to store configurable site settings that administrators can modify through the Django admin interface without requiring code changes.

This model supports caching of settings values for improved performance.

Adding a New Setting

To add a new setting to the database, follow these steps:

Add a new entry to the SiteSettingKey enum class:

Add your new setting key to the SiteSetting enum in recordtransfer/enums.py. The key should be descriptive and follow existing naming conventions (i.e., all uppercase with underscores). Include a SettingKeyMeta with the value type, description, and optional default value.

Example:
```
NEW_SETTING_NAME = SettingKeyMeta(
    SiteSettingType.STR,
    _("Description of what this setting controls."),
    default_value="Default string value",
)
```

Create a data migration:

Create a Django data migration to add the setting to the database. The migration should create a new SiteSetting instance with the required fields:

key: Must be unique and match the enum name (string)
value: The default value as a string (must use the enum’s default_value if available)
value_type: Either “int” for integers or “str” for strings

Example migration for a string setting:

from django.db import migrations


def add_new_setting(apps, schema_editor):
    SiteSetting = apps.get_model("recordtransfer", "SiteSetting")
    SiteSetting.objects.get_or_create(
        key="NEW_SETTING_NAME",
        defaults={"value": "Default string value", "value_type": "str"},
    )


class Migration(migrations.Migration):
    dependencies = [
        ("recordtransfer", "XXXX_previous_migration"),
    ]

    operations = [
        migrations.RunPython(add_new_setting),
    ]

Validation requirements:
- The key field must be unique across all settings
- For value_type “int”: the value must be a valid string representation of an integer (e.g., “42”, “-1”, “0”)
- For value_type “str”: the value can be any string
- change_date is auto-generated and changed_by does not need to be set
Document the new setting:

Add an entry for the new setting to docs/admin_guide/site_settings.rst.

Removing a Setting

To remove an existing setting from the database:

Remove the key from the SiteSettingKey enum class:

Delete the corresponding enum entry from the SiteSetting enum in enums.py.

Create a data migration:

Create a Django data migration to remove the setting from the database:

from django.db import migrations


def remove_old_setting(apps, schema_editor):
    SiteSetting = apps.get_model("recordtransfer", "SiteSetting")
    SiteSetting.objects.filter(key="OLD_SETTING_NAME").delete()


class Migration(migrations.Migration):
    dependencies = [
        ("recordtransfer", "XXXX_previous_migration"),
    ]

    operations = [
        migrations.RunPython(remove_old_setting),
    ]

Update code references:

Remove any code that references the old setting key.
Update documentation:

Remove the setting from docs/admin_guide/site_settings.rst.

Retrieving Settings in Code

Once a setting has been added to the database, retrieve it using the appropriate static method:

For string settings:

value = SiteSetting.get_value_str(SiteSettingKey.SETTING_NAME)

For integer settings:

value = SiteSetting.get_value_int(SiteSettingKey.SETTING_NAME)

set_cache(value: str | int | None) → None: Cache the value of this setting.

static get_value_str(key: SiteSettingKey) → str | None

Get the value of a site setting of type SettingType.STR by its key.

Parameters:: key – The key of the setting to retrieve.
Returns:: The value of the setting as a string, cached if available, or fetched from the database.
Raises:: ValidationError – If the setting is not of type SettingType.STR.

static get_value_int(key: SiteSettingKey) → int | None

Get the value of a site setting of type SettingType.INT by its key.

Parameters:: key – The key of the setting to retrieve.
Returns:: The value of the setting as an integer, cached if available, or fetched from the database.
Raises:: ValidationError – If the setting is not of type SettingType.INT.

reset_to_default(user: User | None = None) → None

Reset this setting to its default value as defined in the SiteSettingKey enum.

Parameters:: user – The user who initiated the reset operation (optional).

property default_value: str | None: Get the default value for this setting, if available. The default value is defined in the SiteSettingKey enum, in the form of a string.

exception DoesNotExist

exception MultipleObjectsReturned

recordtransfer.models.update_cache_post_save(sender: SiteSetting, instance: SiteSetting, created: bool, **kwargs) → None: Update cached value when setting is saved, but not on creation.

class recordtransfer.models.UploadSession(*args, **kwargs)

Represents a file upload session. This model is used to track the files that a user uploads during a session.

The following state diagram illustrates the possible states and transitions for an UploadSession:

        flowchart TD
CREATED --> EXPIRED
CREATED --> UPLOADING
UPLOADING --> CREATED
UPLOADING --> EXPIRED
UPLOADING --> COPYING_IN_PROGRESS
UPLOADING --> REMOVING_IN_PROGRESS
COPYING_IN_PROGRESS --> COPYING_FAILED
COPYING_IN_PROGRESS --> STORED
STORED --> COPYING_IN_PROGRESS
STORED --> REMOVING_IN_PROGRESS
REMOVING_IN_PROGRESS --> CREATED

UploadSession State Diagram

class SessionStatus(value): The status of the session.

classmethod new_session(user: User | None = None) → UploadSession: Start a new upload session.

property upload_size: int: Get total size (in bytes) of all uploaded files in this session. This includes the size of both temporary and permanent files.

property file_count: int: Get the total count of temporary + permanent uploaded files.

property expires_at: datetime | None: Calculate this session’s expiration time. Only sessions in the CREATED, UPLOADING, or EXPIRED state can have an expiration time. Returns None for sessions in other states, or if the upload session expiry feature is disabled.

property is_expired: bool: Determine if this session has expired. A session is considered expired if it is in the EXPIRED state, or if it has gone past its expiration time.

property expires_soon: bool: Determine if this session will expire within the set expiration reminder time.

expires_within(minutes: int) → bool

Determine if this session will expire within the given number of minutes.

Parameters:: minutes – The number of minutes in the future to check for expiration.
Returns:: True if the session will expire before the given number of minutes from now, False otherwise.

expire() → None

Set the status of this session to EXPIRED, but only if the current status is CREATED or UPLOADING.

Raises:: ValueError – If the current status is not CREATED or UPLOADING.

touch(save: bool = True) → None: Reset the last upload interaction time to the current time.

add_temp_file(file: UploadedFile) → TempUploadedFile: Add a temporary uploaded file to this session.

remove_temp_file_by_name(name: str) → None: Remove a temporary uploaded file from this session by name.

get_file_by_name(name: str) → BaseUploadedFile

Get an uploaded file in this session by name. The file can be either temporary or permanent.

Parameters:: name – The name of the file to find

get_temporary_uploads() → list[TempUploadedFile]

Get a list of temporary uploaded files associated with this session.

May be empty if temp uploads have already been moved to permanent storage.

get_permanent_uploads() → list[PermUploadedFile]

Get a list of permanent uploaded files associated with this session.

May be empty if temp uploads have not been moved.

get_uploads() → list[TempUploadedFile] | list[PermUploadedFile]: Get a list of temporary or permanent uploaded files associated with this session. Will return temporary files if in the UPLOADING state, and permanent files if in the STORED state.

remove_temp_uploads(save: bool = True) → None: Remove all temp uploaded files associated with this session.

make_uploads_permanent() → None: Make all temporary uploaded files associated with this session permanent.

copy_session_uploads(destination: str) → tuple[list[str], list[str]]

Copy permanent uploaded files associated with this session to a destination directory.

Parameters:: destination – The destination directory
Returns:: A tuple containing lists of copied and missing files

get_quantity_and_unit_of_measure() → str

Create a human-readable statement of how many files are in this session.

If the session is in the state UPLOADING, returns a count of temp files. If the session is in the state STORED, returns a count of permanent files. If the session is in the state CREATED, returns an appropriate value that indicates the lack of files.

Uses the ACCEPTED_FILE_FORMATS setting to group file types together.

Returns:: A human readable count and size of all files in this session.

exception DoesNotExist

exception MultipleObjectsReturned

recordtransfer.models.session_upload_location(instance: TempUploadedFile, filename: str) → str: Generate the upload location for a session file.

class recordtransfer.models.BaseUploadedFile(*args, **kwargs)

Base class for uploaded files with shared methods.

class Meta: Meta information for the BaseUploadedFile model.

property exists: bool

Determine if the file this object represents exists on the file system.

Returns:: True if file exists, False otherwise
Return type:: (bool)

copy(new_path: str) → None

Copy this file to a new path.

Parameters:: new_path – The new path to copy this file to

remove() → None: Remove this file from the file system.

get_file_media_url() → str

Generate the media URL to this file.

Raises:: FileNotFoundError if the file does not exist. –

get_file_access_url() → str: Generate URL to request access for this file.

class recordtransfer.models.TempUploadedFile(*args, **kwargs)

Represent a temporary file that a user uploaded during an upload session.

move_to_permanent_storage() → None: Move the file from TempFileStorage to UploadedFileStorage.

exception DoesNotExist

exception MultipleObjectsReturned

class recordtransfer.models.PermUploadedFile(*args, **kwargs)

Represent a file that a user uploaded and has been stored.

exception DoesNotExist

exception MultipleObjectsReturned

recordtransfer.models.delete_file_on_model_delete(sender: TempUploadedFile | PermUploadedFile, instance: TempUploadedFile | PermUploadedFile, **kwargs) → None

Delete the actual file when an uploaded file model instance is deleted.

Parameters:

sender – The model class that sent the signal
instance – The model uploaded file instance being deleted
**kwargs – Additional keyword arguments passed to the signal handler

class recordtransfer.models.SubmissionGroup(*args, **kwargs)

Represents a group of submissions.

name

The name of the group

Type:: CharField

description

A description of the group

Type:: TextField

created_by

The user who created the group

Type:: ForeignKey

uuid

A unique ID for the group

Type:: UUIDField

property number_of_submissions_in_group: int: Get the number of submissions in this group.

get_absolute_url() → str: Return the URL to access a detail view of this submission group.

get_delete_url() → str: Return the URL to delete this submission group.

exception DoesNotExist

exception MultipleObjectsReturned

class recordtransfer.models.Submission(*args, **kwargs)

The object that represents a user’s submission, including metadata, and the files they submitted.

submission_date

The date and time the submission was made

Type:: DateTimeField

user

The user who submitted the metadata (and optionally, files)

Type:: User

raw_form

A pickled object containing the transfer form as it was submitted

Type:: BinaryField

metadata

Foreign key to a Metadata object. The metadata object is generated from the form metadata, and any defaults that have been set in the settings

Type:: OneToOneField

part_of_group

The group that this submission is a part of

Type:: ForeignKey

upload_session

The upload session associated with this submission. If file uploads are disabled, this will always be NULL/None

Type:: UploadSession

uuid

A unique ID for the submission

Type:: UUIDField

property bag_name: str

Get a name suitable for a submission bag.

The bag name contains the username, the date this submission was made, and the title of the metadata. This file name is properly sanitized to be used as a directory or part of a file name.

Raises:: ValueError – If there is no metadata or no user associated with this submission.

property extent_statements: str: Return the first extent statement for this submission.

get_admin_metadata_change_url() → str: Get the URL to change the metadata object in the admin.

get_admin_change_url() → str: Get the URL to change this object in the admin.

get_admin_report_url() → str: Get the URL to generate a report for this object in the admin.

get_admin_zip_url() → str: Get the URL to generate a zipped bag for this object in the admin.

make_bag(location: Path, algorithms: Iterable[str] = ('sha512',), file_perms: str = '644') → Bag

Create a BagIt bag on the file system for this Submission. Checks the validity of the Bag post-creation to ensure that integrity is maintained. The data payload files come from the UploadSession associated with this submission.

If given a location to an existing Bag, this function will check whether the Bag can be updated in-place. If not, the Bag will be completely re-generated again.

Raises:

ValueError – If any required state is incorrect (e.g., no upload session)
FileNotFoundError – If any files are missing when copying to temp location
FileExistsError – If the Bag at self.location already exists
bagit.BagValidationError – If the Bag is created, but it’s invalid

Parameters:

location (Path) – The path to make the Bag at
algorithms (Iterable[str]) – The checksum algorithms to generate the BagIt bag with
file_perms (str) – A string-based octal “chmod” number

remove_bag(location: Path) → None: Remove everything in the Bag, including the Bag folder itself.

remove_bag_contents(location: Path) → None: Remove everything in the Bag, but not the Bag directory itself.

exception DoesNotExist

exception MultipleObjectsReturned

class recordtransfer.models.Job(*args, **kwargs)

A background job executed by an admin user.

class JobStatus(value): The status of the bag’s review.

has_file() → bool: Determine if this job has an attached file.

get_file_media_url() → str

Generate the media URL to this file.

Raises:: FileNotFoundError if the file does not exist. –

exception DoesNotExist

exception MultipleObjectsReturned

class recordtransfer.models.InProgressSubmission(*args, **kwargs)

A submission that is in progress, created when a user saves a submission form.

uuid: A unique ID for the submission

user: The user who is submitting the form

last_updated: The last time the form was updated

current_step: The current step the user is on

step_data: The data contained in the form

title: The accession title of the submission

clean() → None: Validate the current step value. This gets called when the model instance is modified through a form.

property upload_session_expires_at: datetime | None: Get the expiration time of the upload session associated with this submission.

property upload_session_expired: bool: Determine if the associated upload session has expired or not.

property upload_session_expires_soon: bool: Determine if the associated upload session is expiring soon or not.

get_resume_url() → str: Get the URL to access and resume the in-progress submission.

get_delete_url() → str: Get the URL to delete this in-progress submission.

reset_reminder_email_sent() → None: Reset the reminder email flag to False, if it isn’t already False.

exception DoesNotExist

exception MultipleObjectsReturned

recordtransfer.models.update_upon_save(sender: InProgressSubmission, instance: InProgressSubmission, **kwargs) → None: Update the last upload interaction time of the associated upload session when the InProgressSubmission is saved, and reset the reminder email flag, if an upload session exists.