heliport.smb_files package

Subpackages

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().

See also Django documentation

class heliport.smb_files.apps.SmbFilesConfig(app_name, app_module)

Bases: AppConfig

The SMB APP.

default_auto_field = 'django.db.models.BigAutoField'
name = 'heliport.smb_files'
ready()

Register types for resolving them.

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.

heliport.smb_files.interface.get_search_url()

Return the search URL for this app.

This URL is used to implement the global HELIPORT string search.

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
access(context: Context)

Get permission checker for this object and context.

See heliport.core.models.DigitalObject.access() for base implementation.

There is also a check that only gives write permission if the current user owns the login.

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.SMBShareModule

Bases: DigitalObjectModule

The module to show SMB shares in HELIPORT project graph.

get_url(project)

List url for SMB shares.

icon = 'fa-solid fa-laptop-file'
module_id = 'smb_shares'
name = 'SMB Shares'
object_class = (<class 'heliport.smb_files.models.DBSMBFile'>, <class 'heliport.smb_files.models.DBSMBDirectory'>)
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', 'namespace_str']
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', 'namespace_str']
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 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 list_url attribute should be a string that is valid when passed to Django’s reverse() function with kwarg “project”. list_url is required by the default action_edit() implementation to link back to original page after editing.

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() 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()).