abstractions Package

abstractions Package

package to abstract the database from the rest of the code.

For users:

submodules are grouped by their overarcing thema such as DJ profiles and users in the same submodule, track information in the same submodule, AFK streamer information in the same submodule, etc.

For developers:

submodules should be of the grouping type where closely related data structures are placed together in a module.

tracks Module

class hanyuu.abstractions.tracks.Length

Bases: int

A simple subclass of int to support formatting on it without having to know the exact format or value in the rest of the code.

format()

Returns unicode:  A formatted [hh:]mm:nn string of the integer.

exception hanyuu.abstractions.tracks.NoTrackEntry

Bases: exceptions.Exception

Raised when a Song instance accesses Track only attributes without having an audio file attached to it.

class hanyuu.abstractions.tracks.Plays(song, sequence)

Bases: list

A simple subclass of list to support some extra attributes.

This class is returned when you access Track.plays and is a collection of play times of the Track in question.

The collection contains datetime.datetime objects or objects that act the same as such with extra methods (for future additions).

add(time, dj=None)

Adds a played entry to the Track object.

The exact time it was played at. :params time: A datetime.datetime instance.

The DJ that played this track at the time. :params dj: A hanyuu.abstractions.users.DJ instance.

Returns None:

Note

It’s good practice to add the DJ argument to all the code already.

The current database however ignores this argument.

last

Returns:The time that last occured. Return type:datetime.datetime object.

remove(time, dj=None)

Removes a played entry from the Track object.

The time this was played at. :params time: A datetime.datetime instance.

The DJ that played this track at the time. If this is None it will be ignored otherwise it will be used for exact matching. :params dj: A hanyuu.abstractions.users.DJ instance.

Returns None:

Note

Currently the dj argument is completely ignored.

save()

Saves changes to the database.

class hanyuu.abstractions.tracks.Requests

Bases: list

A simple subclass of list to support some extra attributes.

last

Returns:The time that last occured. Return type:datetime.datetime object.

class hanyuu.abstractions.tracks.Track(meta, **kwargs)

Bases: object

An instance of a known track in our database. This can also be used for adding new tracks.

A ‘known’ track is one we have seen before. This means there is no difference between tracks we have an audio file of and ones we only know metadata of. The object easily allows you to check if it has a corresponding audio file available or not.

artist

Returns:The artist of this song. Return type:unicode

filename

Returns unicode:  The filename of the audio file. Raises :NoTrackEntry if the song has no audio file.

Note

This is relative to the configured media.directory configuration.

filepath

Returns unicode:  The full path to the audio file. Raises :NoTrackEntry if the song has no audio file.

classmethod from_esong_id(id)

Returns an instance based on the esong table ID.

Warning

Don’t use this method in production code.

classmethod from_track_id(id)

Returns an instance based on the tracks table ID.

Warning

Don’t use this method in production code.

length

Returns:Length of the song or 0 if none available. Return type:Length

Note

The song length is only 100% accurate if the song has an audio file available. Otherwise it’s an approximation from when it was last played.

metadata

Returns:A metadata string of ‘[artist -] title’ where artist is optional Return type:unicode

Note

This uses the tracks table if available before trying the other table.

open(*args, **kwargs)

Opens the associated file and returns a file object.

This handles the path finding for you.

Params unicode mode:  The mode to be passed to the open() call. Returns:An open file object. Raises :NoTrackEntry if the song has no audio file.

plays

Returns:A mutable object with all the playing data in it. Return type:Plays

requests

Returns:A mutable objects with all request data in it. Return type:Requests Raises :NoTrackEntry if the song has no audio file.

save()

Saves all the changes done so far on this object into the database.

Note

This method can do multiple queries to the database depending on the changes done on the object.

title

Returns:The title of this song. Return type:unicode

hanyuu.abstractions.tracks.create_metadata_string(track)

Creates a ‘[artist -] title’ string of the hanyuu.db.models.Track instance.

hanyuu.abstractions.tracks.requires_track(func)

Decorator that raises NoTrackEntry if the song instance has no associated audio file in the database.

Currently this only checks if self._track is falsy.

users Module

A module used for the abstractions of the users part of the database.

class hanyuu.abstractions.users.DJ(id=None, name=None)

Bases: object

Encapsulates the concept of a DJ in our system.

This abstracts the database from the rest of the code. But does return a database related object since it’s a simple one.

classmethod resolve_id(id)

Resolves a DJ identifier to a DJ username.

Returns a class instance or raises DoesNotExist

classmethod resolve_name(name)

Resolves a DJ username to a DJ identifier.

Returns an integer that is the DJ identifier or 0 if the DJ username does not exist.