heliport.smb_files package

Subpackages

heliport.smb_files.migrations package

Submodules

heliport.smb_files.admin module

Registers Django admin pages.

See django.contrib.admin.ModelAdmin from Django documentation.

heliport.smb_files.apps module

Django app configuration.

Some HELIPORT hooks can be registered in app config django.apps.AppConfig.ready().

heliport.smb_files.interface module

Module with special name “interface” hooks into HELIPORT.

Some functions and heliport.core.app_interaction.Module subclasses are detected by HELIPORT and control how HELIPORT uses this app.

Note that this module must be imported in __init__.py of the django app.

class heliport.smb_files.interface.SMBShareModule

Bases: Module

The module to show SMB shares in HELIPORT project graph.

get_url(project): List url for SMB shares.

is_configured(project): shown in project graph when heliport.smb_files.models.DBSMBDirectory exists in project.

module_id = 'smb_shares'

name = 'SMB Shares'

heliport.smb_files.interface.get_search_url(): Register url for searching smb files and directories.

heliport.smb_files.models module

Contains django.db.models.Model classes for Django ORM.

See Quick example from Django documentation. In HELIPORT the heliport.core.models.DigitalObject can be subclassed for models containing metadata in a project.

Models for representing SMB files and directories as Django models (stored in HELIPORT database) or as objects not stored in HELIPORT database.

class heliport.smb_files.models.DBSMBDirectory(*args, **kwargs)

Bases: DigitalObject, DBSMBPath, DirectoryObj

Represent SMBDirectory in database.

exception DoesNotExist: Bases: DoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

as_directory(context: Context) → Directory: Makes this into a directory recognized by HELIPORT.

digitalobject_ptr

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Restaurant.place is a ForwardOneToOneDescriptor instance.

digitalobject_ptr_id

directory_id: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

domain: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

login

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

login_id

path_str: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

server_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

share_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class heliport.smb_files.models.DBSMBFile(*args, **kwargs)

Bases: DigitalObject, DBSMBPath, FileObj

Represent SMBFile in database.

exception DoesNotExist: Bases: DoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

as_file(context: Context) → File: Makes this into a file recognized by HELIPORT.

digitalobject_ptr

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

Restaurant.place is a ForwardOneToOneDescriptor instance.

digitalobject_ptr_id

domain: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

file_id: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

login

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

login_id

path_str: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

server_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

share_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class heliport.smb_files.models.DBSMBPath(*args, **kwargs)

Bases: Model

base class for SMB files and directories stored in heliport database.

class Meta

Bases: object

make this Django model abstract.

abstract = False

domain: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

classmethod from_smb_addr(addr: SMBAddress): Construct a new object from SMBAddress.

classmethod get_by_smb_addr(addr: SMBAddress): Search for an existing object matching the SMBAddress.

login

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

login_id

property path: The path as pathlib Path.

path_str: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

server_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

share_name: A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property smb_addr: The information stored as SMBAddress.

class heliport.smb_files.models.SMBAddress(login: LoginInfo, server_name: str, share_name: str, path: Path, domain: str)

Bases: object

hold the information needed to identify and retrieve some SMB path.

child(file_name) → SMBAddress: Construct the address of the sub path.

domain: str: address or hostname

login: LoginInfo: username and password login for the connection

path: Path: path of the file as pathlib path object

property path_str: Path of the file as string.

server_name: str: name of the smb server

share_name: str: name of the smb share

class heliport.smb_files.models.SMBConn(login: LoginInfo, server_name: str, domain: str)

Bases: object

Immutable dataclass to describe an SMB connection. Implements the heliport.core.utils.context.Description protocol.

Note that the SMB connection is user specific since the login is user specific. This reduces the chance that somebody can use the connection of someone else on top of the fact that the context is specific for a request (and therefore user) anyway.

domain: str: address or hostname

static from_addr(smb_addr: SMBAddress): Get a connection description from SMBAddress.

generate(context): open a new connection; it is closed automatically when used with heliport.core.utils.context.Context.

login: LoginInfo: username and password login for the connection

server_name: str: name of the smb server

class heliport.smb_files.models.SMBDirectory(context: Context, smb_addr: SMBAddress)

Bases: Directory

The actual readable directory object for SMB directories.

property file: SharedFile: Get the smb file metadata object.

get_file_info() → Dict[str, str]: Get human-readable metadata for this directory (only last access time).

get_parts() → Iterable[FileObj | DirectoryObj]: Yield the children of this directory.

class heliport.smb_files.models.SMBDirectoryObj(smb_addr: SMBAddress)

Bases: SMBPathObj, DirectoryObj

represent SMB directory not stored in HELIPORT database.

as_directory(context: Context) → Directory: Makes this into a directory recognized by HELIPORT.

static db_class() → Type[DBSMBPath]: Related Django model is DBSMBDirectory.

static type_id() → str: Type id for resolution is: SMBDirectory.

class heliport.smb_files.models.SMBFile(context: Context, smb_addr)

Bases: File

The actual readable file object for SMB files.

close(): Nothing to close.

property file: SharedFile: Helper function to get the SMB file metadata.

get_file_info(): Get human-readable file metadata (size and last access time).

mimetype() → str: Guesses the mimetype based on file name.

open(): Reset the position back to the beginning.

pos: int: current position in the file (in bytes)

read(number_of_bytes=None): Read number_of_bytes starting from pos.

size(): The file size in bytes.

class heliport.smb_files.models.SMBFileObj(smb_addr: SMBAddress)

Bases: SMBPathObj, FileObj

represent SMB file not stored in HELIPORT database.

as_file(context: Context) → File: Makes this into a file recognized by HELIPORT.

static db_class() → Type[DBSMBPath]: Related Django model is DBSMBFile.

static type_id() → str: Type id for resolution is: SMBFile.

class heliport.smb_files.models.SMBPathObj(smb_addr: SMBAddress)

Bases: ABC, GeneralDigitalObject

base class for objects representing SMB files and directories not in database.

as_digital_object(context: Context) → DigitalObject: Store this object in database or return the one that already exists.

as_html() → str: Present in html using as_text().

as_rdf() → RootedRDFGraph: Serialize just as string for now.

as_text() → str: Present by path name or fall back to share name.

abstract static db_class() → Type[DBSMBPath]: The related Django model (DBSMBFile or DBSMBDirectory.

get_identifying_params() → Dict[str, str]: Parameters from which the object can be resolved using resolve().

classmethod resolve(params: Dict[str, str], context: Context) → GeneralDigitalObject | None: Construct object from identifying parameters; prefer existing one form db.

class heliport.smb_files.models.SMBStat(address: SMBAddress)

Bases: object

description of SMB file metadata; used for caching.

address: SMBAddress: address of the SMB file in question

generate(context): download the metadata; implements the heliport.core.utils.context.Description protocol.

heliport.smb_files.serializers module

This module is for serialization into Datacite, RDF and JSON.

The JSON format is used for API endpoints via Django rest framework. Using this, it is typical to put the serializer classes into a “serializers.py” file.

For the serialization into RDF, attributes are described. See heliport.core.attribute_description.BaseAttribute for more detail.

class heliport.smb_files.serializers.DirectorySerializer(*args, **kwargs)

Bases: ModelSerializer

serialize an SMB directory.

class Meta

Bases: object

describe what should be serialized.

fields = ['directory_id', 'digital_object_id', 'label', 'description', 'projects', 'persistent_id', 'path_str', 'share_name', 'server_name', 'domain', 'login']

model: alias of DBSMBDirectory

class heliport.smb_files.serializers.FileSerializer(*args, **kwargs)

Bases: ModelSerializer

serialize an SMB file.

class Meta

Bases: object

describe what should be serialized.

fields = ['file_id', 'digital_object_id', 'label', 'description', 'projects', 'persistent_id', 'path_str', 'share_name', 'server_name', 'domain', 'login']

model: alias of DBSMBFile

heliport.smb_files.tests module

Test the behaviour of this app.

This follows the Writing tests guide in Django.

class heliport.smb_files.tests.DummyConnection(file_contents=b'', dir_content=())

Bases: object

listPath(share, path)

retrieveFileFromOffset(share, path, data, offset, max_length)

class heliport.smb_files.tests.SMBTests(methodName='runTest')

Bases: WithProject

test_create()

test_directory()

test_file()

test_list()

test_representations()

test_smb_addr()

class heliport.smb_files.tests.SearchAndAPITest(methodName='runTest')

Bases: WithProject

Test search including via API.

test_access_search(): Test that search URL is accessible.

test_api(): Test api.

test_smb_findable(): Test that digital object is findable.

heliport.smb_files.urls module

Map django views to urls.

See this Example including explanation from the Django documentation.

heliport.smb_files.views module

Contains Django View classes to handle HTTP requests.

See Using class-based views from Django documentation. In HELIPORT heliport.core.mixins are used to create uniform views. Also heliport.core.views.generic.HeliportObjectListView is used to quicly create a typical HELIPORT list view.

class heliport.smb_files.views.DirectoryViewSet(**kwargs)

Bases: HeliportModelViewSet

SMB Directories.

Directory contents is available at /api/smb/files/<directory_id>/contents

contents(request, pk=None): Get files and directories in directory.

contents_from_description(request)

Get files and directories in directory.

directory is specified via describing parameters to allow download of subdirectories

filter_backends = [<class 'rest_framework.filters.SearchFilter'>, <class 'django_filters.rest_framework.backends.DjangoFilterBackend'>]

filterset_fields = ['directory_id', 'persistent_id', 'digital_object_id', 'share_name', 'server_name', 'path_str']

get_queryset(): Get directories of user that are not deleted.

search_fields = ['attributes__value', 'path_str', 'server_name', 'share_name']

serializer_class: alias of DirectorySerializer

class heliport.smb_files.views.FileViewSet(**kwargs)

Bases: HeliportModelViewSet

SMB Files.

File contents is available for download at /api/smb/files/<file_id>/download

download(request, pk=None): Get streaming file response to download file contents.

download_from_description(request)

Get streaming file response to download file contents.

The file to download is specified by request parameters. This enables downloading files not directly stored in heliport e.g. inside a directory.

filter_backends = [<class 'rest_framework.filters.SearchFilter'>, <class 'django_filters.rest_framework.backends.DjangoFilterBackend'>]

filterset_fields = ['file_id', 'persistent_id', 'digital_object_id', 'share_name', 'server_name', 'path_str']

get_queryset(): Get files of user that are not deleted.

search_fields = ['attributes__value', 'path_str', 'server_name', 'share_name']

serializer_class: alias of FileSerializer

class heliport.smb_files.views.SMBView

Bases: HeliportObjectListView

View for showing and editing SMB shares.

category = 'SMB/directory': Namespace used for handle generation

create_heading = 'Add a SMB Share': Text displayed as heading over form when creating obj. See also get_create_heading(). # noqa: E501

info_snippet_add = 'core/partials/data_source_warning.html': An HTML template containing a snippet to be used to provide additional information to the “Add” section.

list_heading = 'SMB Shares': Text displayed as heading

list_url = 'smb_files:list': Url that leads to this view for listing objects. The “update_url” string is passed to django.urls.reverse(). # noqa: E501 with “project” url argument to get the actual url. list_url is required by the default action_edit() implementation to link back to original page after edditing. # noqa: E501

model: alias of DBSMBDirectory

register_form_columns(form: FormDescription): Select which (and how) attributes should be included in edit form.

set_update_attributes(obj, form_fields, obj_saved=False): Get login from pk of html form results and set label.

update_url = 'smb_files:update': Url that leads to this view for updating. The “update_url” string is passed to django.urls.reverse(). # noqa: E501 with “project” and “pk” url arguments to get the actual url. update_url is required by the default action_edit() implementation.

class heliport.smb_files.views.SearchView(**kwargs)

Bases: HeliportLoginRequiredMixin, TemplateView

implement HELIPORT search.

get_context_data(**kwargs): Do database query, called by TemplateView.

template_name = 'smb_files/search.html'

Module contents

App to store metadata about and allow access of samba shared files.

The interface module is imported to the top level of the package for HELIPORT app interface discovery (see heliport.core.app_interaction.get_heliport_apps()).