poehlerj / studip-client

CLI Client for the Stud.IP University Access Portal

Stud.IP Client

studip-client is a CLI application for synchronizing the directory tree from a Stud.IP university account to the local file system.

It does this by creating a local database of course files, downloading them into its repository and presenting them in the file system as one or several different views.

studip-client is currently only implemented for the University of Passau (https://uni-passau.de/).

Installation

Make sure you have at least Python 3.4 installed. There are two ways to use studip-client:

Install system-wide

To install the application for all users, run

sudo ./setup.py install

This requires setuptools to be available. The setup script will automatically install all prerequisites and add the studip executable to $PATH.

Then you can simply do

$ studip <operation>

Run from source directory

To run studip-client locally, install all dependencies via

$ pip3 install requests
$ pip3 install appdirs

or a similar command to your package manager. Afterwards, you can run

$ ./studip.py <operation>

Usage

Usually all you'll ever need is

$ studip sync

which will connect to Stud.IP, update the local database and fetch all files not yet present locally.

The general synopsis of studip-client is

$ studip <operation> [-d directory]

The most important operations are

• help: Display a list of operations and options.
• update: Update the local course and file database from Stud.IP.
• fetch: Download all unknown remote files to the local repository
• checkout: Update all views to include newly fetched files
• sync: Do an update followed by fetch and checkout.

If no directory is given, the most recently used one is assumed, if studip-client has not been run before, the directory is read from the standard input.

Configuration

At the moment, the only way to modify studip-client's configuration is by editing <sync-dir>/.studip/studip.conf. It is divided into three sections:

• server: The studip server's base URLs. The only web interface the client has been tested against is uni-passau.de, so changing these settings to connect to other servers will probably not work correctly.

• connection: Controls how studip-client connects to the Stud.IP servers. The concurrency settings controls the maximum number of simultaneous requests.

• user: Login credentials. The password will be encrypted with ~/.cache/studip/secret as the key, which means it cannot be edited directly.

Courses

Courses are added automatically through update and can be managed manually at a later point in time using the course command.

course list will print a list of existing courses and their attributes. Cells marked with * are auto-generated and can be manually set using the editing commands below.

The course set-* family of commands modify one or several courses. The range argument refers to the first column of course list and is of the form 1,3-4,7-9, meaning that the attribute should be set for courses 1, 3, 4, 7, 8 and 9.

• course set-name <range> <name> sets the course name
• course set-abbrev <range> <abbrev> sets the course name abbreviation in case the auto-generated one is not satisfactory
• course set-type <range> <type> sets the course type, e.g. "Lecture"
• course set-tabbrev <range> <tabbrev> overwrites the course type abbreviation

Views

How files are checked out into the sync directory is controlled by views. Each view consists of a directory tree containing hard-links to the original files in .studip/files/. The following operations are available to show and modify views:

• view show: Lists all available views.
• view show <name>: Shows details about a specific view
• view add <name> [<key> <value>...]: Adds a new view, setting the attributes key = value
• view rm <name>: Removes a view and the associated directory structure
• view reset-deleted <name>: Forget about deleted files, allowing them to be checked out again
• view reset-deleted: As above, but for all views.

When studip-client is first invoked, a default view will be created. If you want to change the directory structure, you first need to remove it - If multiple views are to be created, they need to reside in subdirectories, which the default view does not.

For example:

$ studip view rm default
$ studip view add my_view base my_subdir charset ascii

The rm operation removes the directory tree, but keeps any files that weren't created by studip-client. This works even if managed files have been renamed by the user.

Here, when creating the new view, the base attribute is set to my_subdir and the charset to ASCII. The following attributes are available:

• format: A string specifying how each file's path will be built from its metadata. The following placeholders are available:

  {semester}                  Course semester (e.g. "WS 16/17")
  {semester-lexical}          Course semester in lexically sortable format (e.g. "2016WS17")
  {semester-lexical-short}    Course semester in lexically sortable format (e.g. "2016WS")
  {course-id}                 Course hash-id
  {course}                    Course name
  {course-abbrev}             Auto-generated course name abbreviation (e.g. "LinAlgI")
  {type}                      Course type (e.g. "Lecture")
  {type-abbrev}               Abbreviation of the course type (e.g. "L")
  {path}                      Path of the file's containing directory
  {short-path}                Like {path}, but with "Allgemeiner Dateiordner" removed
  {id}                        File hash-id
  {name}                      Original file name, without extension
  {ext}                       File extension (e.g. "pdf")
  {description}               Full file description
  {descr-no-ext}              Like {description}, but with the file extension stripped (if any)
  {author}                    File author's name
  {time}                      Time of creation (e.g. "2017-03-02 13:12")
  

• base: The base directory containing the view's directory tree. If there is only one view, this may be empty. If there are multiple views, each one needs its own subdirectory.

• charset: The class of allowed characters in a file or folder name. Characters which are not in this class are substituted or removed.

  unicode           All unicode characters except / and : are permitted
  ascii             Only ASCII (<= 0x7f) characters are preserved
  identifier        All characters but [A-Za-z0-9_] are removed
  

• escape: Specifies how the path should be encoded to remove invalid characters.

  similar           Replace : and / with similar looking characters
  typeable          Like <similar>, but only uses characters found on a common keyboard
  camel             FilesAndFolders/AreTransformedToCamelCase/WhileRemoving.punctuation
  snake             special_chars/are_replaced_by_underscores/characters_are.lowercase
  

Management

There are additional commands for repository management:

• gc: Delete any fetched file that is not currently checked out in any view. This allows reclaiming disk space after deleting checked-out files.
• clear-cache: Clear the entire database. This is never required in normal operation and should only be used if the database is damaged due to a failed update.

Security

studip-client works by crawling the Stud.IP web interface and will therefore ask for your username and password. The credentials are stored locally in <sync-dir>/.studip/studip.conf and encrypted with a machine-local auto-generated key found in ~/.cache/studip/secret so that simply obtaining a copy of your config file is not enough to recover your password.

All connections to the university servers transporting the login data are made via HTTPS. Your credentials will not be copied or distributed in any other way.

If you're interested in verifying this claim manually, the relevant source code can be found in studip/application.py, Application.open_session().