Skip to main content

nextcloud-orm

Wouldn't it be nice to programmatically manage your nextcloud users and groups with a django-like Object-Relation-Model (ORM), instead of interacting with rather clumsy nextcloud api calls?

import nextcloud_orm
from nextcloud_orm.models import NextcloudUser, NextcloudGroup, NextcloudGroupFolder

# establish connection by using environment variables
nextcloud_orm.connect()
# alternative
#nextcloud_orm.connect(endpoint=YOUR_NEXTCLOUD_URL, user=YOUR_NEXTCLOUD_USERNAME, password=YOUR_NEXTCLOUD_PASSWORD)

# Create a new nextcloud user "Somebody". Attributes like the email can be directly set.
u = NextcloudUser(name='Somebody', password='some_$ecure_password')
u.email = 'some@mail.example'
u.save()

# Create a group "Some Group" if it does not exist already and add "Somebody" to the group
g = NextcloudGroup.objects.get_or_create(name='Some Group')
g.users.add(u)
g.save()

# Create a groupfolder "development" with 2GB quota and make the folder
# accessible for the previously created group without sharing permission
f = NextcloudGroupFolder('development', quota=2 * 1024**3)
f.groups.add(g, share=False)
f.save()

This package wraps the lower level module nextcloud-api-wrapper with a class based ORM.

Supported functionalities

This module essentially supports the functionalities that the nextcloud ocs offers for users, groups and groupfolders (the groupfolders app needs to be installed in nextcloud!). Apart from those, this module wraps installed nextcloud apps by NextcloudApp

If you need other api functionalities, you may access the more complete lower level api by:

from nextcloud_orm.managers import NextcloudManager

# Only accessible after successful connection to nextcloud
nextcloud_orm.connect()

# Lower level api
api = NextcloudManager.api

Core functionallities

Currently there are four nextcloud object models: NextcloudUser, NextcloudGroup, NextcloudGroupFolder and NextcloudApp.

Each of them can be initialized with given arguments and can be syncronized to nextcloud by using NextcloudObject.save():

# unsaved/not synchronized yet
u = NextcloudUser(name='username', email='some@mail.example', displayname='User Name')

try:
    # synchronize user to nextcloud
    u.save()
except NextcloudUser.AlreadyExist as e:
    # the user already exists
    # the lower-level api request can be accessed through 'e.request'
    pass

If the object already exists, an AlreadyExist exception will be raised.

Fetching objects from nextcloud

To access the objects that are already stored, you should use the NextcloudManager instance that is available via NextcloudObject.objects.

In many cases one just wants interact with a nextcloud object, e.g. changing a users email address. To query a single object from nextcloud use NextcloudObject.objects.get()

    # get preexisting user by name
    u = NextcloudUser.objects.get(name='username')
    
    # get preexisting user by email
    u = NextcloudUser.objects.get(email='some@mail.example')

To query every object from nextcloud use NextcloudObject.objects.all(), if you are just interested in a few objects with some particular attributes you may use NextcloudObject.objects.filter()

    # get preexisting user by name
    users = NextcloudUser.objects.all()
    
    for u in users:
        print(u.displayname, u.email)
        
    # filtering example
    unlimited_quota_users = NextcloudUser.objects.filter(quota=None)

A very handy function is get_or_create(defaults, **attributes), which creates the queried user if the user does not exist yet.

    defaults = {'email':'some@mail.example', 'password':'some_$ecure_password', 'displayname':'User Name'}
    u = NextcloudUser.objects.get_or_create(defaults, name='username')

One of the nicest features is that you can access the related objects of an instance via RelatedNextcloudManager attributes, e.g. NextcloudUser.groups handles the group-membership of the user.

    u = NextcloudUser.objects.get(name='username')

    try:
        g = u.groups.get(name='admin')
    except NextcloudGroup.DoesNotExist as e:
        # the user is not a member of 'admin'
        print('The user is not an admin')
        
    # direct checking for containment is also possible
    u.groups.contains('admin')

    # get all groups of the user
    groups = u.groups.all()

The relations between the models can be modified by using add(), remove() and set():

    u = NextcloudUser.objects.get(name='username')

    g = NextcloudGroup('new group')
    g.save()
    
    # add a new group membership
    u.groups.add(g)
    # alternative
    u.groups.add('new group')
    u.save()
    
    # remove group membership, e.g. to disable admin access
    g = NextcloudGroup.objects.get('admin')
    u.groups.remove(g)
    
    # (shorter) alternative
    u.groups.remove('admin')
    u.save()
    
    # setting the related attribute to a list is also possible
    u.groups.set([g])

Mapped relations:

  • group-membership: NextcloudUser.groups and NextcloudGroup.users
  • group-subadmin: NextcloudUser.subadmin and NextcloudGroup.subadmins
  • group-folder: NextcloudGroup.folders and NextcloudGroupFolder.groups

Metadata

Release files for nextcloud-orm 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nextcloud-orm 0.1.0
File Size Uploaded Provenance Actions
nextcloud-orm-0.1.0.tar.gz 16.0 kB Without provenance Details for nextcloud-orm-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nextcloud-orm 0.1.0
File Interpreter ABI Platform Actions
nextcloud_orm-0.1.0-py3-none-any.whl Python 3 none any Details for nextcloud_orm-0.1.0-py3-none-any.whl

Total release size: 35.3 kB

Release files / nextcloud-orm-0.1.0.tar.gz

Download URL nextcloud-orm-0.1.0.tar.gz
Size 16.0 kB
Tags Source
SHA-256 checksum
How to use checksums
17e83ce046384c0c857c07118dd795fbb2a9f1d5a6db09124e859d6d466ec75b
BLAKE2b-256 checksum
How to use checksums
1d673e4c163ad429488c6e31b028c8fccd5a7c1bd4af2dc9c8097ffd048a1872
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.7.1 importlib_metadata/4.8.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.1

Release files / nextcloud_orm-0.1.0-py3-none-any.whl

Download URL nextcloud_orm-0.1.0-py3-none-any.whl
Size 19.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9cae928e6dbcd08a7b5ef4d2f7aab89b20c2245698bfae8da91e3279a0878bb5
BLAKE2b-256 checksum
How to use checksums
c7cbfaae6a0afc19e63ba3746511aa19f7a64eb3e4c1f9057020413c36c419a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.7.1 importlib_metadata/4.8.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.1

Security for nextcloud-orm 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page