Commit 0f83af88 authored by jens.kleineheismann's avatar jens.kleineheismann

Added some docstrings.

parent a082d1f7
ABOUT
=====
This package provide a python binding to the KIT Gruppenverwaltung REST API.
This package provide a python library to access the KIT Gruppenverwaltung REST API.
INSTALLATION
......
"""
Library for accessing KIT Gruppenverwaltung REST API
Library for accessing the KIT Gruppenverwaltung REST API
The most importend class is kitgvapi.ObjectInterface
The object, you are looking for is kitgvapi.ObjectInterface.
"""
__version__ = '1.1'
__author__ = 'Jens Kleineheismann <kleineheismann@kit.edu>'
__author__ = 'Jens Kleineheismann'
__email__ = 'kleineheismann@kit.edu'
__license__ = """
Permission to use, copy, modify, and/or distribute this software
for any purpose with or without fee is hereby granted.
......
"""Clients/Consumer for the remote API provider"""
import json
import requests
......@@ -6,6 +8,14 @@ from .exceptions import NotAllowedError, NotFoundError, MissingConfigError
class RestClientConfig(object):
"""Config for RestClient.
An instance of this class is used to provide the necessary
configuration parameters to a kitgvapi.clients.RestClient
instance.
It takes its default values from kitgvapi.config.DEFAULTS.
"""
def __init__(self):
self.url_schema = DEFAULTS['URL_SCHEMA']
self.server = DEFAULTS['SERVER']
......@@ -42,6 +52,7 @@ class RestClientConfig(object):
@property
def credentials(self):
"""Setup and return a requests.auth.HTTPBasicAuth instance."""
if self._credentials is None:
u = self.username
if u:
......@@ -50,12 +61,23 @@ class RestClientConfig(object):
class RestClient(object):
"""Send requests to the REST API.
- the get_* methods send GET requests and return the
responded and already deserialized JSON data.
Methods, which names end with 's' return a list.
- the add_* and create_* methods send POST requests.
- the remove_* and delete_* methods send DELETE requests.
"""
def __init__(self, config=None):
""":param config: may be an instance of kitgvapi.clients.RestClientConfig. If omitted, a default config is loaded.
"""
self.config = config
if self.config is None:
self.config = RestClientConfig()
def get(self, path):
"""Send GET request."""
url = self.config.url_schema + self.config.server + self.config.base_uri + path
try:
r = requests.get(url, verify=True, auth=self.config.credentials)
......@@ -69,6 +91,7 @@ class RestClient(object):
return d
def post(self, path, data=None):
"""Send POST request."""
if not self.config.enable_post:
raise NotAllowedError("POST operations are disabled by configuration")
url = self.config.url_schema + self.config.server + self.config.base_uri + path
......@@ -80,6 +103,7 @@ class RestClient(object):
return r
def delete(self, path):
"""Send DELETE request."""
if not self.config.enable_delete:
raise NotAllowedError("DELETE operations are disabled by configuration")
raise NotImplementedError("Not ready")
......@@ -152,7 +176,7 @@ class RestClient(object):
def remove_group_user(self, group_pk, user_pk):
raise NotImplementedError("Not ready")
def add_group_group(self, super_pk, sub_pk):
oe_pk = super_pk.partition('-')[0]
path = '/groups/{oe}/{superg}/subgroups/{subg}'.format(oe=oe_pk, superg=super_pk, subg=sub_pk)
......@@ -160,7 +184,7 @@ class RestClient(object):
def remove_group_group(self, super_pk, sub_pk):
raise NotImplementedError("Not ready")
def create_group(self, name, description):
oe_pk = name.partition('-')[0]
path = '/groups/{oe}'.format(oe=oe_pk)
......
from .exceptions import MissingConfigError
"""(Default) Configuration"""
SYMBOLS = {
'GROUP_PK_ATTRIB': 'name',
'OE_PK_ATTRIB': 'kurz',
'USER_PK_ATTRIB': 'samaccount',
}
from .exceptions import MissingConfigError
DEFAULTS = {
'URL_SCHEMA': 'https://',
......@@ -15,3 +11,9 @@ DEFAULTS = {
'ENABLE_POST': True,
'ENABLE_DELETE': False,
}
SYMBOLS = {
'GROUP_PK_ATTRIB': 'name',
'OE_PK_ATTRIB': 'kurz',
'USER_PK_ATTRIB': 'samaccount',
}
"""Exceptions"""
class KitGvApiError(Exception):
pass
......@@ -16,7 +19,7 @@ class MissingPkError(KitGvApiError):
class NotAllowedError(KitGvApiError):
pass
class NotFoundError(KitGvApiError):
pass
"""Type library"""
from .clients import RestClient
from .config import SYMBOLS
from .exceptions import MissingClientError, MissingPkError
class Model(object):
"""Abstract base class"""
def __init__(self, pk=None, client=None, data=None):
self.pk = pk
self.client = client
......@@ -21,7 +24,7 @@ class Model(object):
def _load_data_attribs(self, data=None):
raise NotImplementedError('Abstract method')
def load(self, reload=False):
if self.is_loaded and not reload:
return
......@@ -34,7 +37,7 @@ class Model(object):
def _save_data_attribs(self):
raise NotImplementedError('Abstract method')
def save(self):
if self.client is None:
raise MissingClientError()
......@@ -42,6 +45,7 @@ class Model(object):
class Group(Model):
"""Represent a KIT group"""
def _load_data_attribs(self, data=None):
if data is None:
data = self.client.get_group(pk=self.pk)
......@@ -59,6 +63,7 @@ class Group(Model):
@property
def oe(self):
"""Hold the Oe object, which this group belongs to (read only)."""
return Oe(client=self.client, pk=self.oe_pk)
def get_users(self, effective=False):
......@@ -87,8 +92,9 @@ class Group(Model):
def remove_group(self, pk):
raise NotImplementedError('Not yet')
class Oe(Model):
"""Represent a KIT OE"""
def _load_data_attribs(self, data=None):
if data is None:
data = self.client.get_oe(pk=self.pk)
......@@ -105,7 +111,7 @@ class Oe(Model):
for d in l:
y = Group(client=self.client, data=d)
yield y
def get_users(self):
self.load()
l = self.client.get_oe_users(pk=self.pk)
......@@ -121,6 +127,7 @@ class Oe(Model):
class User(Model):
"""Represent a KIT User account (aka identity)"""
def _load_data_attribs(self, data=None):
if data is None:
data = self.client.get_user(pk=self.pk)
......
"""This module contain the ObjectInterface class."""
from .clients import RestClient
from .models import Group, Oe, User
class ObjectInterface(object):
"""Object oriented interface to the KIT Gruppenverwaltung API"""
class Config(object):
def __init__(self, provider):
self.provider = provider
......@@ -25,7 +29,7 @@ class ObjectInterface(object):
def __init__(self, client=None, client_config=None):
self.config = self.Config(self)
if client is None:
self.client = RestClient(config=client_config)
else:
......@@ -33,12 +37,12 @@ class ObjectInterface(object):
def getOe(self, pk):
return Oe(client=self.client, pk=pk)
def getGroup(self, pk):
return Group(client=self.client, pk=pk)
def newGroup(self, name, description):
raise NotImplementedError("Use kitgvapi.models.Oe.create_group() instead.")
def getUser(self, pk):
return User(client=self.client, pk=pk)
......@@ -2,17 +2,23 @@
from setuptools import setup, find_packages
def package_meta(param):
v = '__' + param + '__'
m = __import__('kitgvapi')
return getattr(m, v)
def readme():
with open('README.rst') as f:
return f.read()
setup(
name='python-kitgvapi',
version='1.1.dev0',
description=('Python bindings for KIT Gruppenverwaltung REST API'),
version=package_meta('version'),
description=package_meta('doc').split('\n')[1],
long_description=readme(),
author='Jens Kleineheismann',
author_email='kleineheismann@kit.edu',
author=package_meta('author'),
author_email=package_meta('email'),
license=package_meta('license'),
url='https://git.scc.kit.edu/zy8373/python-kitgvapi',
packages=find_packages(),
include_package_data=True,
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment