Metadata-Version: 1.1
Name: cred-server
Version: 0.2.5
Summary: Connected Reactive Electronic Devices.
Home-page: https://github.com/Tehnix/cred-server
Author: Tehnix
Author-email: ckl@codetalk.io
License: BSD
Download-URL: https://github.com/Tehnix/cred-server/tarball/v0.2.5
Description: cred
        ====
        **cred** (Connected Reactive Electronic Devices), enables you to connect your
        electronic devices, in a way so that they can communicate with each other
        and react on events happening in the network.
        
        
        An example application cred would be to connect the devices in a living room. If the light switch is connected, and then turned on it would transmit an event like,
        
        ```JSON
        {
            "device": "Light",
            "location": "Living Room",
            "action": "Toggled",
            "value": "On"
        }
        ```
        
        which the thermostat would have subscribe to. The server will then transmit this event to the thermostat when it occurs, and the thermostat could act accordingly, like say turning up the temperature in the room since it's most likely going to be occupied now.
        
        Usage
        =====
        Simply install with pip, add a configuration and run it.
        
        1. `$ pip install cred-server`
        3. `$ cred-server`
        
        and test out the API with curl :)
        
        
        Generating API keys
        =====
        You can generate API keys with the command line utility `cred-gen`. Make sure
        it is using the same configuration as your server. There are three different permission levels,
        
        | Permission | Access                               |
        |------------|--------------------------------------|
        | admin      | All resources                        |
        | write      | All POST and GET except for API keys |
        | read       | All GET except for API keys          |
        
        see `cred-gen --help` for more information on how to use the program.
        
        
        Configuration
        =====
        If you don't supply the configuration location via `--config=/path/to/config`, then the configuration files are searched for in the following order:
            1. Local directory
            2. Users home directory
            3. Users app directory
            4. System app directory
        
        The file searched for is called .credrc for 1. and 2., and without the dot
        for 3. and 4.. If none are found, it will use the default configuration.
        
        Example configuration for a local setup with a SQLite3 database:
        
        ```yaml
        SSL: False
        approot: '127.0.0.1'
        host: '*'
        port: 5000
        database:
          type: 'sqlite3'
          user: ''
          password: ''
          host: ''
          port: ''
          database: 'cred-server.db'
        ```
        
        or using PostgreSQL,
        
        ```yaml
        SSL: False
        approot: '127.0.0.1'
        host: '*'
        port: 5000
        database:
          type: 'postgresql'
          user: 'scott'
          password: 'tiger'
          host: 'localhost'
          port: '5432'
          database: 'mydatabase'
        ```
        
        
        API
        =====
        The URL endpoints and their functionality are described below,
        
        | Resource                        | Method | Function  |
        |---------------------------------|--------|-----------|
        | `/auth`                           | GET    | Authenticate the client and return a session key |
        | `/events`                         | GET    | Return IDs of all events, ordered by ID descending |
        | `/events`                         | POST   | Create a new event associated with the client POSTing it |
        | `/events/<int>`                   | GET    | Return full information for a specific event |
        | `/clients`                        | GET    | Return IDs of all clients that are active |
        | `/clients/me`                     | GET    | Return information about the client itself |
        | `/clients/<int>`                  | GET    | Return information about a specific client |
        | `/clients/<int>/events`           | GET    | Return IDs of all events from the client  |
        | `/clients/<int>/subscribedevents` | GET    | Return IDs of all events the client has subscribed to |
        
        The above resources are accessible with read permissions for all GETs and write for all POSTs and GETs.
        
        | Resource                        | Method | Function |
        |---------------------------------|--------|----------|
        | `/apikeys`                      | GET    | Return IDs of all API keys |
        | `/apikeys`                      | POST   | Generate a new API key |
        | `/apikeys/<int>`                | GET    | Return information about a specific API key |
        
        These resources are special, and require admin permissions.
        
        ### Parameters
        
        Additionally the following query parameters can also be appended to the
        resource, for extra fine-tuning. The parameters below work when using GET
        requests on the following resources: /events and /clients,
        /clients/<int>/events, /clients/<int>/subscribedevents and /apikeys.
        
        | Parameter      | Function                                           |
        |----------------|----------------------------------------------------|
        | `full=<bool>`  | Return the full information instead of just IDs    |
        | `before=<int>` | Returns IDs lower than <int>                       |
        | `after=<int>`  | Returns IDs higher than <int>                      |
        | `limit=<int>`  | Limit the number of items to <int> items           |
        | `offset=<int>` | Skip <int> number of items before fetching         |
        
        
        ### Example API Call
        
        An example call with multiple parameters `/events?full=true&limit=10&offset=10`,
        which will pull the full information for 10 events, starting from after the 10
        newest ones. This can be useful if you want to be able to pull all events and
        paginate them, or something like that. To get the next page, you would then add
        the `&from=` parameter, with the first ID you got back, and increment the offset
        with 10 more.
        
        Alternatively, something like `/clients/<int>/events?full=true` can be used to
        pull the full information for new events that the client has subscribed to.
        
        With the `after=<int>` parameter, the server now doesn't need to keep track of
        when the client last pulled, since the client can control that itself. To give
        an example, a client with ID=145 is doing its first series of requests:
        
        1. The client requests `/clients/145/subscribedevents?full=true&limit=10`
        2. A response with a list of events comes back, the newest being ID=288
        3. The client requests `/clients/145/subscribedevents?from=true&after=288`
        4. A response with all events with ID > 288 comes back
        
        And so on. The minimizes the state kept on the server. If step 2. produced no
        results, the client would set `after=0`, which would still give new events only.
        
        
        Database
        =====
        cred uses SQLAlchemy, so it supports the same database that SQLAlchemy does.
        The `type` setting in the configuration file takes any value that you can find
        at [SQLAlchemy engines](http://docs.sqlalchemy.org/en/latest/core/engines.html "SQLAlchemy engines") (like sqlite3,
        postgresql, postgresql+psycopg2, etc.).
        
        
        Development
        =====
        The following should get you running:
        
        1. `$ git clone git@github.com:Tehnix/cred.git && cd cred-server`
        2. `$ virtualenv env && source env/bin/activate`
        3. `pip install -r requirements.txt`
        4. Run tests with `nosetests` and alternatively with `--with-watch` (detects file changes)
        
        or a one-liner,
        
        ```bash
        $ git clone git@github.com:Tehnix/cred-server.git && cd cred-server && virtualenv env && source env/bin/activate && pip install -r requirements.txt
        ```
        
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Home Automation
Requires: Flask (>=0.10.1)
Requires: FlaskRESTful (>=0.3.2)
Requires: FlaskSQLAlchemy
Requires: FlaskTesting (>=0.4.2)
Requires: pyOpenSSL
Requires: PyYAML
Requires: appdirs
