toyz.utils package — Toyz 0.0.0 documentation

# toyz.utils package

## Subpackages

- toyz.utils.db_interfaces package
  - Submodules
  - toyz.utils.db_interfaces.sqlite_interface module
  - Module contents

## Submodules

## toyz.utils.core module

class `toyz.utils.core.` `Toy`(toy, module=None, path=None, config=None, key=None)

  A toy built on the toyz framework.

  This class has not yet been setup

  `reload`(module)

class `toyz.utils.core.` `ToyzClass`(dict_in)

  I often prefer to work with classes rather than dictionaries. To allow these objects to be pickled they must be defined as a class, so this is simply a class that converts a dictionary into a class.

class `toyz.utils.core.` `ToyzJobQueue`(queue_name, process_count)

  An environment for a single user to run tasks.

  No longer implemented, but may be in the future

  `add_job`(job)
  `close_env`(interrupt_jobs=False)
  `initialize`()
  `job_worker`(queue)

class `toyz.utils.core.` `ToyzSettings`(config_root_path=None)

  Settings for the current toyz application.

  `first_time_setup`(config_root_path)

    Initial setup of the Toyz application and creation of files the first time it’s run.

    Parameters
      - config_root_path (string ): Default root path of the new Toyz instance
  `load_settings`(config_path, security_key=None)

    Load settings. If `toyz_settings.security.encrypt_config` is True, the settings file will be decrypted (this requires a securiity key).

    Security not yet implemented

  `save_settings`(security_key=None)

    Save the toyz settings to disk. If toyz_settings.security.encrypt_config is True, the settings file will be encrypted (this requires a security key).

    Security not yet implemented

class `toyz.utils.core.` `ToyzUser`(toyz_settings, **user_settings)

  User logged into the Toyz web application.

  No longer implemented

  `add_toyz`(toyz, paths)

    Add a toyz from a list of packages and/or a list of paths on the server

    toyz: list
      - elements are either names of packages built on the toyz framework or dictionaries,

      where the keys are names to identify each package and the values are package names.

    paths: dict of strings
      - Keys are names to identify each toy
      - Values are paths to modules that have not been packaged but fit the toyz framework

    None

`toyz.utils.core.` `check4keys`(myDict, keys)

  Checks a dictionary for a set of required keys.

  Parameters
    - myDict (dict ): Dictionary to be searched
    - keys (list ): List of keys to search for in the dictionary
  Raises
    Raises a `toyz.utils.errors.ToyzJobError` if any keys are missing from `myDict` and lists all of the missing keys

`toyz.utils.core.` `check_instance`(obj, instances)

  Check if an object is an instance of another object

  Parameters
    - obj (object ): Object to check
    - instances (list ): List of objects to crosscheck with obj
  Returns
    - is_instance (bool ): True if the obj is an instances of one of the objects in the list, False otherwise

`toyz.utils.core.` `check_pwd`(toyz_settings, user_id, pwd)

  Check to see if a users password matches the one stored in the database.

  Parameters
    - toyz_settings ( `toyz.utils.core.ToyzSettings` ): Settings for the current application
    - user_id (string ): Id of the user logging in
    - pwd: (string ): password the user has entered
  Returns
    - valid_login (bool ): True if the user name and password match

`toyz.utils.core.` `check_user_shortcuts`(toyz_settings, user_id, shortcuts=None)

  Check that a user has all of the default shortcuts.

  Parameters
    - toyz_settings ( `toyz.utils.core.ToyzSettings` ): Toyz Settings
    - user_id (string ): User id to check for shortcuts
    - shortcuts (dict, optional): Dictionary of shortcuts for a user. Shortcuts are always of the form `shortcut_name:path` .

`toyz.utils.core.` `create_paths`(paths)

  Search for paths on the server. If a path does not exist, create the necessary directories. For example, if `paths=['~/Documents/images/2014-6-5_data/']` and only the path ‘~/Documents’ exists, both ‘~/Documents/images/’ and ‘~/Documents/images/2014-6-5_data/’ are created.

  Parameters
    paths (string or list of strings): If paths is a string, this is the path to search for and create. If paths is a list, each one is a path to search for and create

`toyz.utils.core.` `encrypt_pwd`(toyz_settings, pwd)

  Use the passlib module to create a hash for the given password.

  Parameters
    - toyz_settings ( `toyz.utils.core.ToyzSettings` ): Settings for the current application
    - pwd (string ): password the user has entered
  Returns
    - pwd_hash (string ): Password hash to be stored for the given password. If passwords are not encrypted, this will just return the `pwd` passed to the function.

`toyz.utils.core.` `get_bool`(prompt)

  Prompt a user for a boolean expression and repeat until a valid boolean has been entered. `prompt` is the text to prompt the user with.

`toyz.utils.core.` `get_user_type`(params)

  Since user properties and group properties are kept in the same table and use the same functions, many functions use the keyword user_id or group_id to figure out if they are operating on groups or users.

  Parameters
    - params (dict ): Dictionary of parameters sent to a function
  Returns
    - user (dict ): Dictionary with user_type. This is always either `{user_id: params['user_id']}` or `{group_id: params['group_id']}`

`toyz.utils.core.` `normalize_path`(path)

  Format a path with bash symbols like ‘~‘ , ‘.‘ , ‘..‘ into a full absolute path. This simply returns `os.path.abspath(os.path.expanduser(path))` .

`toyz.utils.core.` `run_job`(toyz_settings, job)

  Loads modules and runs a job (function) sent from a client. Any errors will be trapped and flagged as a `toyz.utils.errors.ToyzError` and sent back to the client who initiated the job.

  All job functions will take exactly 3 parameters: toyz_settings, tid, params. The tid is the task id (user, session, and request_id ) information (see below), and params is a dictionary of parameters sent by the client.

  Each job is run as a new process, so any modules imported should be removed from memory when the job has completed.

  Parameters
    toyz_settings ( `toyz.utils.core.ToyzSettings` ):
      - Settings for the application runnning the job (may be needed to load user info or check permissions)
    job: dict
      - The job received from the user. Each job will contain the following keys:
      - `id` (dict): Unique values for the given job. These are the user_id, the id of the user loaded from a secure cookie; the session_id, a unique identifier for the websocket; and the request_id, a unique identifier for the current request, sent from the client
      - `module` (str): Name of the Python module that contains the function called by the client. In order for a module to work for a user, he/she must either have permissions set to view the module or belong to a group with permissions set to view the module (including all_users).
      - `task` (str): Name of the function called by the client
      - `parameters` (dict): Required and optional parameters passed to the function.
  Returns
    result: dict
      - The result is returned to the application running the job and is composed of two keys: an `id`: the job id for the completed job, and a `response` that is sent to the client.
      - The response is either an empty dictionary or one that contains (at a minimum) the key id, which is used by the client to identify the type of response it is receiving. Including the key request_completed with a True value tells the client that the current request has finished and may be removed from the queue.

  Example

  > A client might send the following job to the server:

  >     job = {
  >         id : {
  >             user_id : 'Iggy',
  >             session_id : '12',
  >             request_id : 305
  >         },
  >         module : 'toyz.web.tasks',
  >         task : 'load_directory',
  >         parameters : {
  >             path: '~/images'
  >         }
  >     }

  > In this case, after receiving the job, this function will import the `toyz.web.tasks` module (if it has not been imported already) and run the function `load_directory(toyz_settings, job['id'],job['parameters'])`. If there are any errors in loading the directory, a response of the form

  >     response = {
  >         'id' : 'ERROR',
  >         'error' : 'Error message here for unable to lead directory',
  >         'traceback' : traceback.format_exec()
  >     }

  > is sent. If the directory is loaded correctly a response of the form

  >     response={
  >         'id': 'directory',
  >         'path': '~/images/proj1',
  >         'shortcuts': ['user', 'temp', 'home'],
  >         'folders': ['proj1', 'proj2'],
  >         'files': [],
  >         'parent': '~/images'
  >     }

  > is sent to the client.

`toyz.utils.core.` `str_2_bool`(bool_str)

  Case independent function to convert a string representation of a boolean (true/false, yes/no) into a bool. This is case insensitive, and will also accept part of a boolean string (t/f, y/n).

  Raises a `toyz.utils.errors.ToyzError` if an invalid expression is entered.

## toyz.utils.db module

To keep Toyz database agnostic this module works as a stardard API to access any database interfaces written into the framework. Currently on the `sqlite` interface is supported.

`toyz.utils.db.` `check_chars`(err_flag, *lists)

  Check if every value in every list is alpha-numeric.

  Parameters
    - err_flag (bool ):
        - If err_flag is True, an exception will be raised if the field is not alpha_numeric.
        - If err_flag is False, the function will return False
    - lists (lists):
        - Each list in lists must be a list of strings, each one a keyword to verify if it is alpha-numeric

`toyz.utils.db.` `create_toyz_database`(db_settings)

  Create a new Toyz database. This should only be done when creating a new instance of a Toyz application.

`toyz.utils.db.` `db_func`(db_settings, func, **params)

  Function from a database outside of the database API.

`toyz.utils.db.` `delete_param`(db_settings, param_type, **params)

  Delete a parameter from the database.

`toyz.utils.db.` `get_all_ids`(db_settings, user_type)

  Get all user_id’s or group_id’s in the database.

`toyz.utils.db.` `get_param`(db_settings, param_type, **params)

  Get a parameter from the database. This may be either a single value, dictionary, or list of values, depending on the parameter.

`toyz.utils.db.` `get_path_info`(db_settings, path)

  Get the permissions for all users and groups for a given path.

`toyz.utils.db.` `init`(**params)

  For some databases it might be necessary to initialize them on startup, so this function call `init` in the current database interface

`toyz.utils.db.` `update_all_params`(db_settings, param_type, **params)

  Update a parameter with a single value, a list of values, or a dictionary. In the case of a list or a dictionary, this function also removes any entries in the database not contained in `params` .

`toyz.utils.db.` `update_param`(db_settings, param_type, **params)

  Update a parameter with a single value, list of values, or dictionary.

## toyz.utils.errors module

Error classes used in Toyz.

exception `toyz.utils.errors.` `Error`

  Bases: `exceptions.Exception`

  Base class for custom errors related to the running of Toyz

exception `toyz.utils.errors.` `ToyzDbError`(msg)

  Bases: `toyz.utils.errors.ToyzError`

  Class for errors initiating in the Toyz Database Interface

exception `toyz.utils.errors.` `ToyzError`(msg)

  Bases: `toyz.utils.errors.Error`

  Class for custom errors related to the running of Toyz.

exception `toyz.utils.errors.` `ToyzJobError`(msg)

  Bases: `toyz.utils.errors.ToyzError`

  Class for errors initiating in the Toyz Job Queue

class `toyz.utils.errors.` `ToyzWarning`(msg)

  Class for warnings

exception `toyz.utils.errors.` `ToyzWebError`(msg)

  Bases: `toyz.utils.errors.ToyzError`

  Class for errors initiating in the Toyz Web Application

## toyz.utils.file_access module

Utilities to access path and file permissions for the server.

`toyz.utils.file_access.` `get_all_parents`(path)

  Create a list with all of the parent directories of the file or path.

  For example `/Users/penny/Documents` would be returned as `['/Users/penny/Documents', '/Users/penny', '/Users/']`

`toyz.utils.file_access.` `get_file_permissions`(db_settings, path, **user)

  Get all of the permissions for a given path. Returns None type if no permissions have been set.

  Parameters
    - db_settings (object ): Database settings
    - path (string ): Path to check for permissions
    - user (dict ): Key is either user_id or group_id, value is the user_id or group_id
  Return
    - permissions (string ): Permissions for the given user for the given path. Returns None if no permissions have been set.

`toyz.utils.file_access.` `get_parent_permissions`(db_settings, path, **user)

  Find the permissions of the given path. If it doesn’t have any permissions explicitely set, descend a tree and find the first parent directory with permissions set. If no permissions can be found, None is returned.

  Parameters
    - db_settings (object ): Database settings
    - path (string ): Path to check for permissions
    - user (dict ): Key is either user_id or group_id, value is the user_id or group_id
  Return
    - permissions (string ): Permissions for the given user for the given path. Returns None if no permissions have been set for any parent paths.

`toyz.utils.file_access.` `get_path_tree`(path)

  Get all of the sub directories of path.

`toyz.utils.file_access.` `split_path`(path_in)

  Splits a path into a list of its folders.

  For example `/Users/penny/Documents` would be returned as `['Users', 'penny', 'Documents']`

## toyz.utils.security module

Security Functions for Toyz Copyright 2014 by Fred Moolekamp License: MIT

`toyz.utils.security.` `decrypt_pickle`(app_settings, key)

  Use the provided key to decrypt the config file. Not yet supported

`toyz.utils.security.` `encrypt_pickle`(app_settings)

  Encrypt the app settings using a config file. Not yet supported

## toyz.utils.third_party_settings module

Settings for 3rd party web libraries, including jquery, jquery_ui, jquery_ui_themes. These are the defaults for any third party libraries, containing version information and a path to the source code.

## Module contents

Common non-package specific utility functions