The API allows access to agent update packages, possibly through redirects

class pyfarm.master.api.agent_updates.AgentUpdatesAPI[source]¶

Bases: flask.views.MethodView

get(version)[source]¶

A GET to this endpoint will return the update package as a zip file the specified version

GET /api/v1/agents/updates/<string:version> HTTP/1.1¶

Request

PUT /api/v1/agents/updates/1.2.3 HTTP/1.1
Accept: application/zip

Response

HTTP/1.1 200 OK
Content-Type: application/zip

<binary data>

Statuscode 200:	The update file was found and is returned
Statuscode 301:	The update can be found under a different URL
Statuscode 400:	there was something wrong with the request (such as an invalid version number specified or the mime type not being application/zip)

methods = ['GET', 'PUT']¶

put(version)[source]¶

A PUT to this endpoint will upload a new version of pyfarm-agent to be used for agent auto-updates. The update must be a zip file.

PUT /api/v1/agents/updates/<string:version> HTTP/1.1¶

Request

PUT /api/v1/agents/updates/1.2.3 HTTP/1.1
Content-Type: application/zip

<binary data>

Response

HTTP/1.1 200 OK
Content-Type: application/json

Statuscode 201:	The update was put in place
Statuscode 400:	there was something wrong with the request (such as an invalid version number specified or the mime type not being application/zip)

Contained within this module are an API handling functions which can manage or query agents using JSON.

class pyfarm.master.api.agents.AgentIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of known agents, with id and name.

GET /api/v1/agents/ HTTP/1.1¶

Request

GET /api/v1/agents/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "hostname": "agent1",
        "id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3"
    },
    {
        "hostname": "agent2",
        "id": "8326779e-90b5-447c-8da8-1eaa154771d9"
    },
    {
        "hostname": "agent3.local",
        "id": "14b28230-64a1-4b62-803e-5fd1baa209e4"
    }
]

Request (with filters)

GET /api/v1/agents/?min_ram=4096&min_cpus=4 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "hostname": "foobar",
    "port": 50000,
    "remote_ip": "127.0.0.1",
    "id": "e20bae92-6472-442e-98a8-0ea4c9ee41cd"
  }
]

Qparam min_ram:	If set, list only agents with min_ram ram or more
Qparam max_ram:	If set, list only agents with max_ram ram or less
Qparam min_cpus:
	If set, list only agents with min_cpus cpus or more
Qparam max_cpus:
	If set, list only agents with max_cpus cpus or less
Qparam hostname:
	If set, list only agents matching hostname
Qparam remote_ip:
	If set, list only agents matching remote_ip
Qparam port:	If set, list only agents matching port.
Statuscode 200:	no error, host may or may not have been found

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will either create or update an existing agent. The port and id columns will determine if an agent already exists.

• If an agent is found matching the port and id columns from the request the existing model will be updated and the resulting data and the OK code will be returned.
• If we don’t find an agent matching the port and id however a new agent will be created and the resulting data and the CREATED code will be returned.

Note

The remote_ip field is not required and should typically not be included in a request. When not provided remote_ip is be populated by the server based off of the ip of the incoming request. Providing remote_ip in your request however will override this behavior.

POST /api/v1/agents/ HTTP/1.1¶

Request

POST /api/v1/agents/ HTTP/1.1
Accept: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "free_ram": 133,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "remote_ip": "10.196.200.115",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": 8
 }

Response (agent created)

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": "remote",
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": "online",
    "remote_ip": "10.196.200.115"
 }

Response (existing agent updated)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": "remote",
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "6a0c11df-660f-4c1e-9fb4-5fe2b8cd2437",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": "online",
    "remote_ip": "10.196.200.115"
 }

Statuscode 201:	a new agent was created
Statuscode 200:	an existing agent is updated with data from the request
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

class pyfarm.master.api.agents.SingleAgentAPI[source]¶

Bases: flask.views.MethodView

API view which is used for retrieving information about and updating single agents.

delete(agent_id)[source]¶

Delete a single agent

DELETE /api/v1/agents/(uuid: agent_id) HTTP/1.1¶

Request (agent exists)

DELETE /api/v1/agents/b25ee7eb-9586-439a-b131-f5d022e0d403 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Statuscode 204:	the agent was deleted or did not exist

get(agent_id)[source]¶

Return basic information about a single agent

GET /api/v1/agents/(str: agent_id) HTTP/1.1¶

Request (agent exists)

GET /api/v1/agents/4eefca76-1127-4c17-a3df-c1a7de685541 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": 311,
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "322360ad-976f-4103-9acc-a811d43fd24d",
    "ip": "10.196.200.115",
    "port": 64994,
    "ram": 2157,
    "ram_allocation": 0.8,
    "state": 202,
    "remote_ip": "10.196.200.115"
 }

Request (no such agent)

GET /api/v1/agents/4eefca76-1127-4c17-a3df-c1a7de685541 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{"error": "Agent `4eefca76-1127-4c17-a3df-c1a7de685541` not "
          "found"}

Statuscode 200:	no error
Statuscode 400:	something within the request is invalid
Statuscode 404:	no agent could be found using the given id

methods = ['DELETE', 'GET', 'POST']¶

post(agent_id)[source]¶

Update an agent’s columns with new information by merging the provided data with the agent’s current definition in the database.

POST /api/v1/agents/(str: agent_id) HTTP/1.1¶

Request

POST /api/v1/agents/29d466a5-34f8-408a-b613-e6c2715077a0 HTTP/1.1
Accept: application/json

{"ram": 1234}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "cpu_allocation": 1.0,
    "cpus": 14,
    "use_address": 311,
    "free_ram": 133,
    "time_offset": 0,
    "hostname": "agent1",
    "id": "29d466a5-34f8-408a-b613-e6c2715077a0",
    "ip": "10.196.200.115",
    "port": 64994,
    "ram": 1234,
    "ram_allocation": 0.8,
    "state": "running",
    "remote_ip": "10.196.200.115"
}

Statuscode 200:	no error
Statuscode 400:	something within the request is invalid
Statuscode 404:	no agent could be found using the given id

class pyfarm.master.api.agents.TasksInAgentAPI[source]¶

Bases: flask.views.MethodView

get(agent_id)[source]¶

A GET to this endpoint will return a list of all tasks assigned to this agent.

GET /api/v1/agents/<str:agent_id>/tasks/ HTTP/1.1¶

Request

GET /api/v1/agents/bbf55143-f2b1-4c15-9d41-139bd8057931/tasks/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "state": "assign",
        "priority": 0,
        "job": {
            "jobtype": "TestJobType",
            "id": 1,
            "title": "Test Job",
            "jobtype_version": 1,
            "jobtype_id": 1
        },
        "hidden": false,
        "time_started": null,
        "project_id": null,
        "frame": 2.0
        "agent_id": "bbf55143-f2b1-4c15-9d41-139bd8057931",
        "id": 2,
        "attempts": 2,
        "project": null,
        "time_finished": null,
        "time_submitted": "2014-03-06T15:40:58.338904",
        "job_id": 1
    }
]

Statuscode 200:	no error
Statuscode 404:	agent not found

methods = ['GET', 'POST']¶

post(agent_id)[source]¶

A POST to this endpoint will assign am existing task to the agent.

POST /api/v1/agents/<str:agent_id>/tasks/ HTTP/1.1¶

Request

POST /api/v1/agents/238d7334-8ca5-4469-9f54-e76c66614a43/tasks/ HTTP/1.1
Accept: application/json

{
    "id": 2
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "agent_id": 1,
    "parents": [],
    "attempts": 2,
    "children": [],
    "job": {
        "title": "Test Job",
        "id": 1
    },
    "project_id": null,
    "agent": {
        "ip": null,
        "hostname": "agent1",
        "port": 50000,
        "id": "238d7334-8ca5-4469-9f54-e76c66614a43"
    },
    "hidden": false,
    "job_id": 1,
    "time_submitted": "2014-03-06T15:40:58.338904",
    "frame": 2.0,
    "priority": 0,
    "state": "assign",
    "time_finished": null,
    "id": 2,
    "project": null,
    "time_started": null
}

Statuscode 200:	no error
Statuscode 404:	agent not found

pyfarm.master.api.agents.fail_missing_assignments(agent, current_assignments)[source]¶

pyfarm.master.api.agents.or_(*clauses)¶

Produce a conjunction of expressions joined by OR.

E.g.:

from sqlalchemy import or_

stmt = select([users_table]).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

The or_() conjunction is also available using the Python | operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):

stmt = select([users_table]).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

See also

and_()

pyfarm.master.api.agents.schema()[source]¶

Returns the basic schema of Agent

GET /api/v1/agents/schema HTTP/1.1¶

Request

GET /api/v1/agents/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ram": "INTEGER",
    "free_ram": "INTEGER",
    "time_offset": "INTEGER",
    "use_address": "INTEGER",
    "hostname": "VARCHAR(255)",
    "cpus": "INTEGER",
    "port": "INTEGER",
    "state": "INTEGER",
    "ram_allocation": "FLOAT",
    "cpu_allocation": "FLOAT",
    "id": "UUIDType",
    "remote_ip": "IPv4Address"
}

Statuscode 200:	no error

This module defines an API for managing and querying job queues

class pyfarm.master.api.jobqueues.JobQueueIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of known job queues.

GET /api/v1/jobqueues/ HTTP/1.1¶

Request

GET /api/v1/jobqueues/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "priority": 5,
        "weight": 10,
        "parent_jobqueue_id": null,
        "name": "Test Queue",
        "minimum_agents": null,
        "id": 1,
        "maximum_agents": null
    },
    {
        "priority": 5,
        "weight": 10,
        "parent_jobqueue_id": null,
        "name": "Test Queue 2",
        "minimum_agents": null,
        "id": 2,
        "maximum_agents": null
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will create a new job queue.

POST /api/v1/jobqueues/ HTTP/1.1¶

Request

POST /api/v1/jobqueues/ HTTP/1.1
Accept: application/json

{
    "name": "Test Queue"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "weight": 10,
    "jobs": [],
    "minimum_agents": null,
    "priority": 5,
    "name": "Test Queue",
    "maximum_agents": null,
    "id": 1,
    "parent": null,
    "parent_jobqueue_id": null
}

Statuscode 201:	a new job queue was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 409:	a job queue with that name already exists

class pyfarm.master.api.jobqueues.SingleJobQueueAPI[source]¶

Bases: flask.views.MethodView

delete(queue_rq)[source]¶

A DELETE to this endpoint will delete the specified job queue

DELETE /api/v1/jobqueue/HTTP/[<str:name>|<int:id>] 1.1¶

Request

DELETE /api/v1/jobs/Test%20Queue HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the job queue was deleted or didn’t exist
Statuscode 409:	the job queue cannot be deleted because it still contains jobs or child queues

get(queue_rq)[source]¶

A GET to this endpoint will return the requested job queue

GET /api/v1/jobqueues/[<str:name>|<int:id>] HTTP/1.1¶

Request

GET /api/v1/software/Test%20Queue HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "parent": [],
    "jobs": [],
    "weight": 10,
    "parent_jobqueue_id": null,
    "priority": 5,
    "minimum_agents": null,
    "name": "Test Queue",
    "maximum_agents": null
}

Statuscode 200:	no error
Statuscode 404:	the requested job queue was not found

methods = ['DELETE', 'GET', 'POST']¶

post(queue_rq)[source]¶

A POST to this endpoint will update the specified queue with the data in the request. Columns not specified in the request will be left as they are.

POST /api/v1/jobqueues/[<str:name>|<int:id>] HTTP/1.1¶

Request

PUT /api/v1/jobs/Test%20Queue HTTP/1.1
Accept: application/json

{
    "priority": 6
}

Response

HTTP/1.1 201 OK
Content-Type: application/json

{
    "id": 1,
    "parent": [],
    "jobs": [],
    "weight": 10,
    "parent_jobqueue_id": null,
    "priority": 6,
    "minimum_agents": null,
    "name": "Test Queue",
    "maximum_agents": null
}

Statuscode 200:	the job queue was updated
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

pyfarm.master.api.jobqueues.schema()[source]¶

Returns the basic schema of JobQueue

GET /api/v1/jobqueues/schema HTTP/1.1¶

Request

GET /api/v1/jobqueues/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "INTEGER",
    "name": VARCHAR(255)",
    "minimum_agents": "INTEGER",
    "maximum_agents": "INTEGER",
    "priority": "INTEGER",
    "weight": "INTEGER",
    "parent_jobqueue_id": "INTEGER"
}

Statuscode 200:	no error

This module defines an API for managing and querying jobs

class pyfarm.master.api.jobs.JobIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of all jobs.

GET /api/v1/jobs/ HTTP/1.1¶

Request

GET /api/v1/jobs/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "title": "Test Job",
        "state": "queued",
        "id": 1
    },
    {
        "title": "Test Job 2",
        "state": "queued",
        "id": 2
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will submit a new job.

POST /api/v1/jobs/ HTTP/1.1¶

Request

POST /api/v1/jobs/ HTTP/1.1
Accept: application/json

{
    "end": 2.0,
    "title": "Test Job 2",
    "jobtype": "TestJobType",
    "data": {
        "foo": "bar"
    },
    "software_requirements": [
        {
        "software": "blender"
        }
    ],
    "start": 1.0
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "time_finished": null,
    "time_started": null,
    "end": 2.0,
    "time_submitted": "2014-03-06T15:40:58.335259",
    "jobtype_version": 1,
    "jobtype": "TestJobType",
    "jobqueue": None
    "start": 1.0,
    "priority": 0,
    "state": "queued",
    "parents": [],
    "hidden": false,
    "project_id": null,
    "ram_warning": null,
    "title": "Test Job 2",
    "tags": [],
    "user": null,
    "by": 1.0,
    "data": {
        "foo": "bar"
    },
    "ram_max": null,
    "notes": "",
    "batch": 1,
    "project": null,
    "environ": null,
    "requeue": 3,
    "software_requirements": [
        {
            "min_version": null,
            "max_version": null,
            "max_version_id": null,
            "software_id": 1,
            "min_version_id": null,
            "software": "blender"
        }
    ],
    "id": 2,
    "ram": 32,
    "cpus": 1,
    "children": []
}

Statuscode 201:	a new job item was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 404:	a referenced object, like a software or software version, does not exist
Statuscode 409:	a conflicting job already exists

class pyfarm.master.api.jobs.JobNotifiedUsersIndexAPI[source]¶

Bases: flask.views.MethodView

get(job_name)[source]¶

A GET to this endpoint will return a list of all users to be notified on events in this job.

GET /api/v1/jobs/[<str:name>|<int:id>]/notified_users/ HTTP/1.1¶

Request

GET /api/v1/jobs/Test%20Job%202/notified_users/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "username": "testuser",
        "email": "testuser@localhost"
    }
]

Statuscode 200:	no error
Statuscode 404:	job not found

methods = ['GET', 'POST']¶

post(job_name)[source]¶

A POST to this endpoint will add the specified user to the list of notified users for this job.

POST /api/v1/jobs/[<str:name>|<int:id>]/notified_users/ HTTP/1.1¶

Request

POST /api/v1/jobs/Test%20Job/notified_users/ HTTP/1.1
Accept: application/json

{
    "username": "testuser"
    "on_success": true,
    "on_failure": true,
    "on_deletion": false
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1
    "username": "testuser"
    "email": "testuser@example.com"
}

Statuscode 201:	a new notified user entry was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 404:	the job or the specified user does not exist

class pyfarm.master.api.jobs.JobSingleNotifiedUserAPI[source]¶

Bases: flask.views.MethodView

delete(job_name, username)[source]¶

A DELETE to this endpoint will remove the specified user from the list of notified users for this job.

DELETE /api/v1/jobs/[<str:name>|<int:id>]/notified_users/<str:username> HTTP/1.1¶

Request

DELETE /api/v1/jobs/Test%20Job/notified_users/testuser HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the notified user was removed from this job or wasn’t in the list in the first place
Statuscode 404:	the job or the specified user does not exist

methods = ['DELETE']¶

class pyfarm.master.api.jobs.JobSingleTaskAPI[source]¶

Bases: flask.views.MethodView

get(job_name, task_id)[source]¶

A GET to this endpoint will return the requested task

GET /api/v1/jobs/[<str:name>|<int:id>]/tasks/<int:task_id> HTTP/1.1¶

Request

GET /api/v1/jobs/Test%20Job%202/tasks/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "time_finished": null,
    "agent": null,
    "attempts": 0,
    "frame": 2.0,
    "agent_id": null,
    "job": {
        "id": 1,
        "title": "Test Job"
    },
    "time_started": null,
    "state": "running",
    "project_id": null,
    "id": 2,
    "time_submitted": "2014-03-06T15:40:58.338904",
    "project": null,
    "parents": [],
    "job_id": 1,
    "hidden": false,
    "children": [],
    "priority": 0
}

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post(job_name, task_id)[source]¶

A POST to this endpoint will update the specified task with the data in the request. Columns not specified in the request will be left as they are. The agent will use this endpoint to inform the master of its progress.

POST /api/v1/jobs/[<str:name>|<int:id>]/tasks/<int:task_id> HTTP/1.1¶

Request

PUT /api/v1/job/Test%20Job/tasks/1 HTTP/1.1
Accept: application/json

{
    "state": "running"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "time_finished": null,
    "agent": null,
    "attempts": 0,
    "failures": 0,
    "frame": 2.0,
    "agent_id": null,
    "job": {
        "id": 1,
        "title": "Test Job"
    },
    "time_started": null,
    "state": "running",
    "project_id": null,
    "id": 2,
    "time_submitted": "2014-03-06T15:40:58.338904",
    "project": null,
    "parents": [],
    "job_id": 1,
    "hidden": false,
    "children": [],
    "priority": 0
}

Statuscode 200:	the task was updated
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

class pyfarm.master.api.jobs.JobTasksIndexAPI[source]¶

Bases: flask.views.MethodView

get(job_name)[source]¶

A GET to this endpoint will return a list of all tasks in a job.

GET /api/v1/jobs/[<str:name>|<int:id>]/tasks HTTP/1.1¶

Request

GET /api/v1/jobs/Test%20Job%202/tasks/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "hidden": false,
        "id": 3,
        "attempts": 0,
        "priority": 0,
        "time_started": null,
        "time_submitted": "2014-03-06T15:49:51.892228",
        "frame": 1.0,
        "time_finished": null,
        "job_id": 2,
        "project_id": null,
        "state": "queued",
        "agent_id": null
    },
    {
        "hidden": false,
        "id": 4,
        "attempts": 0,
        "priority": 0,
        "time_started": null,
        "time_submitted": "2014-03-06T15:49:51.892925",
        "frame": 2.0,
        "time_finished": null,
        "job_id": 2,
        "project_id": null,
        "state": "queued",
        "agent_id": null
    }
]

Statuscode 200:	no error

methods = ['GET']¶

exception pyfarm.master.api.jobs.ObjectNotFound[source]¶

Bases: Exception

class pyfarm.master.api.jobs.SingleJobAPI[source]¶

Bases: flask.views.MethodView

delete(job_name)[source]¶

A DELETE to this endpoint will mark the specified job for deletion and remove it after stopping and removing all of its tasks.

DELETE /api/v1/jobs/[<str:name>|<int:id>] HTTP/1.1¶

Request

DELETE /api/v1/jobs/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the specified job was marked for deletion
Statuscode 404:	the job does not exist

get(job_name)[source]¶

A GET to this endpoint will return the specified job, by name or id.

GET /api/v1/jobs/[<str:name>|<int:id>] HTTP/1.1¶

Request

GET /api/v1/jobs/Test%20Job%202 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ram_warning": null,
    "title": "Test Job",
    "state": "queued",
    "jobtype_version": 1,
    "jobtype": "TestJobType",
    "environ": null,
    "user": null,
    "priority": 0,
    "time_finished": null,
    "start": 2.0,
    "id": 1,
    "notes": "",
    "notified_users": []
    "ram": 32,
    "tags": [],
    "hidden": false,
    "data": {
        "foo": "bar"
    },
    "software_requirements": [
        {
            "software": "blender",
            "software_id": 1,
            "min_version": null,
            "max_version": null,
            "min_version_id": null,
            "max_version_id": null
        }
    ],
    "batch": 1,
    "time_started": null,
    "time_submitted": "2014-03-06T15:40:58.335259",
    "requeue": 3,
    "end": 4.0,
    "parents": [],
    "cpus": 1,
    "ram_max": null,
    "children": [],
    "by": 1.0,
    "project_id": null
}

Statuscode 200:	no error
Statuscode 404:	job not found

methods = ['DELETE', 'GET', 'POST']¶

post(job_name)[source]¶

A POST to this endpoint will update the specified job with the data in the request. Columns not specified in the request will be left as they are. If the “start”, “end” or “by” columns are updated, tasks will be created or deleted as required.

POST /api/v1/jobs/[<str:name>|<int:id>] HTTP/1.1¶

Request

PUT /api/v1/jobs/Test%20Job HTTP/1.1
Accept: application/json

{
    "start": 2.0
}

Response

HTTP/1.1 201 OK
Content-Type: application/json

{
    "end": 4.0,
    "children": [],
    "jobtype_version": 1,
    "jobtype": "TestJobType",
    "time_started": null,
    "tasks_failed": [],
    "project_id": null,
    "id": 1,
    "software_requirements": [
        {
            "software": "blender",
            "min_version": null,
            "max_version_id": null,
            "software_id": 1,
            "max_version": null,
            "min_version_id": null
        }
    ],
    "tags": [],
    "environ": null,
    "requeue": 3,
    "start": 2.0,
    "ram_warning": null,
    "title": "Test Job",
    "batch": 1,
    "time_submitted": "2014-03-06T15:40:58.335259",
    "ram_max": null,
    "user": null,
    "notes": "",
    "data": {
        "foo": "bar"
    },
    "ram": 32,
    "parents": [],
    "hidden": false,
    "priority": 0,
    "cpus": 1,
    "state": "queued",
    "by": 1.0,
    "time_finished": null
}

Statuscode 200:	the job was updated
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

pyfarm.master.api.jobs.and_(*clauses)¶

Produce a conjunction of expressions joined by AND.

E.g.:

from sqlalchemy import and_

stmt = select([users_table]).where(
                and_(
                    users_table.c.name == 'wendy',
                    users_table.c.enrolled == True
                )
            )

The and_() conjunction is also available using the Python & operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):

stmt = select([users_table]).where(
                (users_table.c.name == 'wendy') &
                (users_table.c.enrolled == True)
            )

The and_() operation is also implicit in some cases; the Select.where() method for example can be invoked multiple times against a statement, which will have the effect of each clause being combined using and_():

stmt = select([users_table]).\
            where(users_table.c.name == 'wendy').\
            where(users_table.c.enrolled == True)

See also

or_()

pyfarm.master.api.jobs.or_(*clauses)¶

Produce a conjunction of expressions joined by OR.

E.g.:

from sqlalchemy import or_

stmt = select([users_table]).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

The or_() conjunction is also available using the Python | operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):

stmt = select([users_table]).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

See also

and_()

pyfarm.master.api.jobs.parse_requirements(requirements)[source]¶

Takes a list dicts specifying a software and optional min- and max-versions and returns a list of JobRequirement objects.

Raises TypeError if the input was not as expected or ObjectNotFound if a referenced software of or version was not found.

Parameters:	requirements (list) – A list of of dicts specifying a software and optionally min_version and/or max_version.
Raises:	TypeError – Raised if requirements is not a list or if an entry in requirements is not a dictionary. ValueError – Raised if there’s a problem with the content of at least one of the requirement dictionaries. ObjectNotFound – Raised if the referenced software or version was not found

pyfarm.master.api.jobs.schema()[source]¶

Returns the basic schema of Job

GET /api/v1/jobs/schema HTTP/1.1¶

Request

GET /api/v1/jobs/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "batch": "INTEGER",
    "by": "NUMERIC(10, 4)",
    "cpus": "INTEGER",
    "data": "JSONDict",
    "end": "NUMERIC(10,4)",
    "environ": "JSONDict",
    "hidden": "BOOLEAN",
    "id": "INTEGER",
    "jobtype": "VARCHAR(64)",
    "jobtype_version": "INTEGER",
    "jobqueue": "VARCHAR(255)",
    "notes": "TEXT",
    "priority": "INTEGER",
    "project_id": "INTEGER",
    "ram": "INTEGER",
    "ram_max": "INTEGER",
    "ram_warning": "INTEGER",
    "requeue": "INTEGER",
    "start": "NUMERIC(10,4)",
    "state": "WorkStateEnum",
    "time_finished": "DATETIME",
    "time_started": "DATETIME",
    "time_submitted": "DATETIME",
    "title": "VARCHAR(255)",
    "user": "VARCHAR(255)"
}

Statuscode 200:	no error

This module defines an API for managing and querying jobtypes

class pyfarm.master.api.jobtypes.JobTypeCodeAPI[source]¶

Bases: flask.views.MethodView

get(jobtype_name, version)[source]¶

A GET to this endpoint will return just the python code for this version of the specified jobtype.

GET /api/v1/jobtypes/[<str:name>|<int:id>]/versions/<int:version>/code HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType/versions/1/code HTTP/1.1
Accept: text/x-python

Response

HTTP/1.1 200 OK
Content-Type: text/x-python

from pyfarm.jobtypes.core.jobtype import JobType

class TestJobType(JobType):
    def get_command(self):
        return "/usr/bin/touch"

    def get_arguments(self):
        return [os.path.join(
            self.assignment_data["job"]["data"]["path"], "%04d" %
            self.assignment_data["tasks"][0]["frame"])]

Statuscode 200:	no error
Statuscode 404:	jobtype or version not found

methods = ['GET']¶

class pyfarm.master.api.jobtypes.JobTypeIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of registered jobtypes.

GET /api/v1/jobtypes/ HTTP/1.1¶

Request

GET /api/v1/jobtypes/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "TestJobType"
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will create a new jobtype.

POST /api/v1/jobtypes/ HTTP/1.1¶

Request

POST /api/v1/jobtypes/ HTTP/1.1
Accept: application/json

{
    "name": "TestJobType",
    "classname": "TestJobType",
    "description": "Jobtype for testing inserts and queries",
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "batch_contiguous": true,
    "software_requirements": [],
    "version": 1,
    "max_batch": 1,
    "name": "TestJobType",
    "classname": "TestJobType",
    "description": "Jobtype for testing inserts and queries",
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n"
}

Statuscode 201:	a new jobtype item was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 409:	a conflicting jobtype already exists

class pyfarm.master.api.jobtypes.JobTypeSoftwareRequirementAPI[source]¶

Bases: flask.views.MethodView

delete(jobtype_name, software)[source]¶

A DELETE to this endpoint will delete the requested software requirement from the specified jobtype, creating a new version of the jobtype in the process

DELETE /api/v1/jobtypes/[<str:name>|<int:id>]/software_requirements/<int:id> HTTP/1.1¶

Request

DELETE /api/v1/jobtypes/TestJobType/software_requirements/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO CONTENT

Statuscode 204:	the software requirement was deleted or didn’t exist

get(jobtype_name, software)[source]¶

A GET to this endpoint will return the specified software requirement from the newest version of the requested jobtype.

GET /api/v1/jobtypes/[<str:name>|<int:id>]/software_requirements/<int:id> HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType/software_requirements/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "software": {
        "software": "/bin/touch",
        "id": 1
    },
    "max_version": null,
    "min_version": {
        "version": "8.21",
        "id": 1
    },
    "jobtype_version": {
        "version": 7,
        "jobtype": "TestJobType"
    }
}

Statuscode 200:	no error
Statuscode 404:	jobtype or software requirement not found

methods = ['DELETE', 'GET']¶

class pyfarm.master.api.jobtypes.JobTypeSoftwareRequirementsIndexAPI[source]¶

Bases: flask.views.MethodView

get(jobtype_name, version=None)[source]¶

A GET to this endpoint will return a list of all the software requirements of the specified jobtype

GET /api/v1/jobtypes/[<str:name>|<int:id>]/software_requirements/ HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType/software_requirements/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "software": {
            "software": "/bin/touch",
            "id": 1
        },
        "max_version": null,
        "min_version": {
            "version": "8.21",
            "id": 1
        },
        "jobtype_version": {
            "version": 7,
            "jobtype": "TestJobType"
        }
    }
]

Statuscode 200:	no error
Statuscode 404:	jobtype or version not found

methods = ['GET', 'POST']¶

post(jobtype_name, version=None)[source]¶

A POST to this endpoint will create a new software_requirement for the specified jobtype. This will transparently create a new jobtype version

POST /api/v1/jobtypes/[<str:name>|<int:id>]/software_requirements/ HTTP/1.1¶

Request

POST /api/v1/jobtypes/TestJobType/software_requirements/ HTTP/1.1
Accept: application/json

{
    "software": "blender",
    "min_version": "2.69"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "jobtype_version": {
        "id": 8,
        "jobtype": "TestJobType",
        "version": 7
    },
    "max_version": null,
    "min_version": {
        "id": 2,
        "version": "1.69"
    },
    "software": {
        "id": 2,
        "software": "blender"
    }
}

Statuscode 201:	a new software requirement was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 405:	you tried calling this method on a specific version
Statuscode 409:	a conflicting software requirement already exists

class pyfarm.master.api.jobtypes.JobTypeVersionsIndexAPI[source]¶

Bases: flask.views.MethodView

get(jobtype_name)[source]¶

A GET to this endpoint will return a sorted list of of all known versions of the specified jobtype.

GET /api/v1/jobtypes/[<str:name>|<int:id>]/versions/ HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType/versions/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[1, 2]

Statuscode 200:	no error
Statuscode 404:	jobtype not found

methods = ['GET']¶

exception pyfarm.master.api.jobtypes.ObjectNotFound[source]¶

Bases: Exception

class pyfarm.master.api.jobtypes.SingleJobTypeAPI[source]¶

Bases: flask.views.MethodView

delete(jobtype_name)[source]¶

A DELETE to this endpoint will delete the requested jobtype

DELETE /api/v1/jobtypes/[<str:name>|<int:id>] HTTP/1.1¶

Request

DELETE /api/v1/jobtypes/TestJobType HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO CONTENT

Statuscode 204:	the jobtype was deleted or didn’t exist

get(jobtype_name)[source]¶

A GET to this endpoint will return the most recent version of the referenced jobtype, by name or id.

GET /api/v1/jobtypes/<str:tagname> HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "batch_contiguous": true,
    "classname": null,
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n",
    "id": 1,
    "version": 1,
    "max_batch": 1,
    "name": "TestJobType",
    "software_requirements": [
        {
            "max_version": null,
            "max_version_id": null,
            "min_version": "8.21",
            "min_version_id": 1,
            "software": "/bin/touch",
            "software_id": 1
        }
    ]
}

Statuscode 200:	no error
Statuscode 404:	jobtype or version not found

methods = ['DELETE', 'GET', 'PUT']¶

put(jobtype_name)[source]¶

A PUT to this endpoint will create a new jobtype under the given URI. If a jobtype already exists under that URI, a new version will be created with the given data.

You should only call this by id for updating an existing jobtype or if you have a reserved jobtype id. There is currently no way to reserve a jobtype id.

PUT /api/v1/jobtypes/[<str:name>|<int:id>] HTTP/1.1¶

Request

PUT /api/v1/jobtypes/TestJobType HTTP/1.1
Accept: application/json

{
    "name": "TestJobType",
    "description": "Jobtype for testing inserts and queries",
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "batch_contiguous": true,
    "classname": null,
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n",
    "id": 1,
    "max_batch": 1,
    "name": "TestJobType", 
    "description": "Jobtype for testing inserts and queries",
    "software_requirements": []
}

Statuscode 201:	a new jobtype was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

class pyfarm.master.api.jobtypes.VersionedJobTypeAPI[source]¶

Bases: flask.views.MethodView

delete(jobtype_name, version)[source]¶

A DELETE to this endpoint will delete the requested version of the specified jobtype.

DELETE /api/v1/jobtypes/[<str:name>|<int:id>]/versions/<int:version> HTTP/1.1¶

Request

DELETE /api/v1/jobtypes/TestJobType/versions/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO CONTENT

Statuscode 204:	the version was deleted or didn’t exist

get(jobtype_name, version)[source]¶

A GET to this endpoint will return the specified version of the referenced jobtype, by name or id.

GET /api/v1/jobtypes/[<str:name>|<int:id>]/versions/<int:version> HTTP/1.1¶

Request

GET /api/v1/jobtypes/TestJobType/versions/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "batch_contiguous": true,
    "classname": null,
    "name": "TestJobType",
    "code": "\nfrom pyfarm.jobtypes.core.jobtype import "
            "JobType\n\nclass TestJobType(JobType):\n"
            "    def get_command(self):\n"
            "        return "/usr/bin/touch"\n\n"
            "    def get_arguments(self):\n"
            "           return [os.path.join("
            "self.assignment_data["job"]["data"]["path"], "
            ""%04d" % self.assignment_data["tasks"]"
            "[0]["frame"])]\n",
    "id": 1,
    "version": 1,
    "max_batch": 1,
    "software_requirements": [
        {
            "max_version": null,
            "max_version_id": null,
            "min_version": "8.21",
            "min_version_id": 1,
            "software": "/bin/touch",
            "software_id": 1
        }
    ]
}

Statuscode 200:	no error
Statuscode 404:	jobtype or version not found

methods = ['DELETE', 'GET']¶

pyfarm.master.api.jobtypes.or_(*clauses)¶

Produce a conjunction of expressions joined by OR.

E.g.:

from sqlalchemy import or_

stmt = select([users_table]).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

The or_() conjunction is also available using the Python | operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):

stmt = select([users_table]).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

See also

and_()

pyfarm.master.api.jobtypes.parse_requirements(requirements)[source]¶

Takes a list dicts specifying a software and optional min- and max-versions and returns a list of JobRequirement objects.

Raises TypeError if the input was not as expected or ObjectNotFound if a referenced software of or version was not found.

Parameters:	requirements (list) – A list of of dicts specifying a software and optionally min_version and/or max_version.
Raises:	TypeError – Raised if requirements is not a list or if an entry in requirements is not a dictionary. ValueError – Raised if there’s a problem with the content of at least one of the requirement dictionaries. ObjectNotFound – Raised if the referenced software or version was not found

pyfarm.master.api.jobtypes.schema()[source]¶

Returns the basic schema of JobType

GET /api/v1/jobtypes/schema HTTP/1.1¶

Request

GET /api/v1/jobtypes/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "batch_contiguous": "BOOLEAN",
    "classname": "VARCHAR(64)",
    "code": "TEXT",
    "description": "TEXT",
    "id": "INTEGER",
    "version": "INTEGER",
    "max_batch": "INTEGER",
    "name": "VARCHAR(64)"
}

Statuscode 200:	no error

API endpoints for viewing and managing path maps

class pyfarm.master.api.pathmaps.PathMapIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of all registered path maps, with id. It can be made with a for_agent query parameter, in which case it will return only those path maps that apply to that agent.

GET /api/v1/pathmaps/ HTTP/1.1¶

Request

GET /api/v1/pathmaps/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "path_osx": "/mnt/nfs",
        "path_windows": "\\domains\cifs_server",
        "path_linux": "/mnt/nfs"
    },
    {
        "id": 7,
        "path_osx": "/renderout",
        "path_windows": "c:\renderout",
        "path_linux": "/renderout"
        "tag": "usual",
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will create a new path map.

A path map will list the equivalent path prefixes for all three supported families of operating systems, Linux, Windows and OS X. A path map can optionally be restricted to one tag, in which case it will only apply to agents with that tag. If a tag is specified that does not exist yet, that tag will be transparently created.

POST /api/v1/pathmaps/ HTTP/1.1¶

Request

POST /api/v1/pathmaps/ HTTP/1.1
Accept: application/json

{
    "path_linux": "/mnt/nfs",
    "path_windows": "\domain\cifs_server",
    "path_osx": "/mnt/nfs",
    "tag": "production"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "path_linux": "/mnt/nfs",
    "path_windows": "\domain\cifs_server",
    "path_osx": "/mnt/nfs",
    "tag": "production"
}

Statuscode 201:	a new pathmap was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

class pyfarm.master.api.pathmaps.SinglePathMapAPI[source]¶

Bases: flask.views.MethodView

delete(pathmap_id)[source]¶

A DELETE to this endpoint will remove the specified pathmap

DELETE /api/v1/pathmaps/<int:pathmap_id> HTTP/1.1¶

Request

DELETE /api/v1/pathmaps/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the path map was deleted or did not exist in the first place

get(pathmap_id)[source]¶

A GET to this endpoint will return a single path map specified by pathmap_id

GET /api/v1/pathmaps/<int:pathmap_id> HTTP/1.1¶

Request

GET /api/v1/pathmaps/1 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "path_osx": "/mnt/nfs",
    "path_windows": "\\domains\cifs_server",
    "path_linux": "/mnt/nfs"
}

Statuscode 200:	no error

methods = ['DELETE', 'GET', 'POST']¶

post(pathmap_id)[source]¶

A POST to this endpoint will update an existing path map with new values.

Only the values included in the request will be updated. The rest will be left unchanged. The id column cannot be changed. Including it in the request will lead to an error.

POST /api/v1/pathmaps/<int:pathmap_id> HTTP/1.1¶

Request

POST /api/v1/pathmaps/1 HTTP/1.1
Accept: application/json

{
    "path_linux": "/mnt/smb"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "path_linux": "/mnt/smb",
    "path_windows": "\domain\cifs_server",
    "path_osx": "/mnt/nfs",
    "tag": "production"
}

Statuscode 200:	the specified pathmap was updated
Statuscode 404:	the specified pathmap does not exist
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

pyfarm.master.api.pathmaps.or_(*clauses)¶

Produce a conjunction of expressions joined by OR.

E.g.:

from sqlalchemy import or_

stmt = select([users_table]).where(
                or_(
                    users_table.c.name == 'wendy',
                    users_table.c.name == 'jack'
                )
            )

The or_() conjunction is also available using the Python | operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):

stmt = select([users_table]).where(
                (users_table.c.name == 'wendy') |
                (users_table.c.name == 'jack')
            )

See also

and_()

pyfarm.master.api.pathmaps.schema()[source]¶

Returns the basic schema of Agent

GET /api/v1/pathmaps/schema HTTP/1.1¶

Request

GET /api/v1/pathmaps/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "INTEGER",
    "path_linux": "VARCHAR(512)",
    "path_windows": "VARCHAR(512)",
    "path_osx": "VARCHAR(512)",
    "tag": "VARCHAR(64)"
}

Statuscode 200:	no error

Contained within this module are an API handling functions which can manage or query software items using JSON.

class pyfarm.master.api.software.SingleSoftwareAPI[source]¶

Bases: flask.views.MethodView

delete(software_rq)[source]¶

A DELETE to this endpoint will delete the requested software tag

DELETE /api/v1/software/<str:softwarename> HTTP/1.1¶

Request

DELETE /api/v1/software/Autodesk%20Maya HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the software tag was deleted or didn’t exist

get(software_rq)[source]¶

A GET to this endpoint will return the requested software tag

GET /api/v1/software/<str:softwarename> HTTP/1.1¶

Request

GET /api/v1/software/Autodesk%20Maya HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "software": "Autodesk Maya",
    "id": 1,
    "versions": [
        {
            "version": "2013",
            "id": 1,
            "rank": 100
        },
        {
            "version": "2014",
            "id": 2,
            "rank": 200
        }
    ]
}

Statuscode 200:	no error
Statuscode 404:	the requested software tag was not found

methods = ['DELETE', 'GET', 'PUT']¶

put(software_rq)[source]¶

A PUT to this endpoint will create a new software tag under the given URI or update an existing software tag if one exists. Renaming existing software tags via this call is supported, but when creating new ones, the included software name must be equal to the one in the URI.

You should only call this by id for overwriting an existing software tag or if you have a reserved software id. There is currently no way to reserve a tag id.

PUT /api/v1/software/<str:softwarename> HTTP/1.1¶

Request

PUT /api/v1/software/blender HTTP/1.1
Accept: application/json

{
    "software": "blender"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 4,
    "software": "blender",
    "versions": []
}

Request

PUT /api/v1/software/blender HTTP/1.1
Accept: application/json

{
    "software": "blender",
    "version": [
        {
            "version": "1.69"
        }
    ]
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 4,
    "software": "blender",
    "versions": [
        {
            "version": "1.69",
            "id": 1,
            "rank": 100
        }
    ]
}

Statuscode 200:	an existing software tag was updated
Statuscode 201:	a new software tag was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

class pyfarm.master.api.software.SingleSoftwareVersionAPI[source]¶

Bases: flask.views.MethodView

delete(software_rq, version_name)[source]¶

A DELETE to this endpoint will delete the requested software version

DELETE /api/v1/software/<str:softwarename>/versions/<str:version> HTTP/1.1¶

Request

DELETE /api/v1/software/Autodesk%20Maya/versions/2013 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 204 NO_CONTENT

Statuscode 204:	the software version was deleted or didn’t exist
Statuscode 404:	the software specified does not exist

get(software_rq, version_name)[source]¶

A GET to this endpoint will return the specified version

GET /api/v1/software/<str:softwarename>/versions/<str:version> HTTP/1.1¶

Request

GET /api/v1/software/Autodesk%20Maya/versions/2014 HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": "2013",
    "id": 1,
    "rank": 100
}

Statuscode 200:	no error
Statuscode 404:	the requested software tag or version was not found

methods = ['DELETE', 'GET']¶

class pyfarm.master.api.software.SoftwareIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of known software, with all known versions.

GET /api/v1/software/ HTTP/1.1¶

Request

GET /api/v1/software/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "software": "Houdini",
        "id": 1,
        "versions": [
            {
                "version": "13.0.1",
                "id": 1,
                "rank": 100
            }
        ]
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will create a new software tag.

A list of versions can be included. If the software item already exists the listed versions will be added to the existing ones. Versions with no explicit rank are assumed to be the newest version available. Users should not mix versions with an explicit rank with versions without one.

POST /api/v1/software/ HTTP/1.1¶

Request

POST /api/v1/software/ HTTP/1.1
Accept: application/json

{
    "software": "blender"
}

Response (new software item create)

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 4,
    "software": "blender",
    "versions": []
}

Statuscode 201:	a new software item was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 409:	a software tag with that name already exists

class pyfarm.master.api.software.SoftwareVersionsIndexAPI[source]¶

Bases: flask.views.MethodView

get(software_rq)[source]¶

A GET to this endpoint will list all known versions for this software

GET /api/v1/software/<str:softwarename>/versions/ HTTP/1.1¶

Request

GET /api/v1/software/Autodesk%20Maya/versions/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "version": "2013",
        "id": 1,
        "rank": 100
    },
    {
        "version": "2014",
        "id": 2,
        "rank": 200
    }
]

Statuscode 200:	no error
Statuscode 404:	the requested software tag was not found

methods = ['GET', 'POST']¶

post(software_rq)[source]¶

A POST to this endpoint will create a new version for this software.

A rank can optionally be included. If it isn’t, it is assumed that this is the newest version for this software

POST /api/v1/software/versions/ HTTP/1.1¶

Request

POST /api/v1/software/blender/versions/ HTTP/1.1
Accept: application/json

{
    "version": "1.70"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 4,
    "version": "1.70",
    "rank": "100"
}

Statuscode 201:	a new software version was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 409:	a software version with that name already exists

exception pyfarm.master.api.software.VersionParseError[source]¶

Bases: Exception

Raised by extract_version_dicts() when the function is unable to parse a version.

pyfarm.master.api.software.extract_version_dicts(json_in)[source]¶

Extracts and returns a list of versions from json_in.

pyfarm.master.api.software.schema()[source]¶

Returns the basic schema of Software

GET /api/v1/software/schema HTTP/1.1¶

Request

GET /api/v1/software/schema HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "INTEGER",
    "software": "VARCHAR(64)"
}

Statuscode 200:	no error

Contained within this module are an API handling functions which can manage or query tags using JSON.

class pyfarm.master.api.tags.AgentsInTagIndexAPI[source]¶

Bases: flask.views.MethodView

get(tagname=None)[source]¶

A GET to this endpoint will list all agents associated with this tag.

GET /api/v1/tags/<str:tagname>/agents/ HTTP/1.1¶

Request

GET /api/v1/tags/interesting/agents/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

[
    {
        "hostname": "agent3",
        "id": 1,
        "href": "/api/v1/agents/1
    }
]

Statuscode 200:	the list of agents associated with this tag is returned
Statuscode 404:	the tag specified does not exist

methods = ['GET', 'POST']¶

post(tagname=None)[source]¶

A POST will add an agent to the list of agents tagged with this tag The tag can be given as a string or as an integer (its id).

POST /api/v1/tags/<str:tagname>/agents/ HTTP/1.1¶

Request

POST /api/v1/tags/interesting/agents/ HTTP/1.1
Accept: application/json

{
    "agent_id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3"
}

Response (agent newly tagged)

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "href": "/api/v1/agents/1",
    "id": 1
}

Request

POST /api/v1/tags/interesting/agents/ HTTP/1.1
Accept: application/json

{
    "agent_id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3"
}

Response (agent already had that tag)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "href": "/api/v1/agents/1",
    "id": 1
}

Statuscode 200:	an existing tag was found and returned
Statuscode 201:	a new tag was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 404:	either the tag or the referenced agent does not exist

class pyfarm.master.api.tags.SingleTagAPI[source]¶

Bases: flask.views.MethodView

delete(tagname=None)[source]¶

A DELETE to this endpoint will delete the tag under this URI, including all relations to tags or jobs.

DELETE /api/v1/tags/<str:tagname> HTTP/1.1¶

Request

DELETE /api/v1/tags/interesting HTTP/1.1
Accept: application/json

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "tag": "interesting"
}

Statuscode 204:	the tag was deleted or did not exist in the first place

get(tagname=None)[source]¶

A GET to this endpoint will return the referenced tag, either by name or id, including a list of agents and jobs associated with it.

GET /api/v1/tags/<str:tagname> HTTP/1.1¶

Request

GET /api/v1/tags/interesting HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "agents": [{
        "hostname": "agent3",
        "href": "/api/v1/agents/94522b7e-817b-4358-95da-670b31aad624",
        "id": 1
    }],
    "id": 1,
    "jobs": [],
    "tag": "interesting"
}

Statuscode 200:	no error
Statuscode 404:	tag not found

methods = ['DELETE', 'GET', 'PUT']¶

put(tagname=None)[source]¶

A PUT to this endpoint will create a new tag under the given URI. If a tag already exists under that URI, it will be deleted, then recreated. Note that when overwriting a tag like that, all relations that are not explicitly specified here will be deleted You can optionally specify a list of agents or jobs relations as integers in the request data.

You should only call this by id for overwriting an existing tag or if you have a reserved tag id. There is currently no way to reserve a tag id.

PUT /api/v1/tags/<str:tagname> HTTP/1.1¶

Request

PUT /api/v1/tags/interesting HTTP/1.1
Accept: application/json

{
    "tag": "interesting"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "tag": "interesting"
}

Request

PUT /api/v1/tags/interesting HTTP/1.1
Accept: application/json

{
    "tag": "interesting",
    "agents": [1]
    "jobs": []
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "tag": "interesting"
}

Statuscode 201:	a new tag was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 404:	a referenced agent or job does not exist

class pyfarm.master.api.tags.TagIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

A GET to this endpoint will return a list of known tags, with id. Associated agents and jobs are included for every tag

:rtype : object .. http:get:: /api/v1/tags/ HTTP/1.1

Request

GET /api/v1/tags/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "agents": [
            1
        ],
        "jobs": [],
        "id": 1,
        "tag": "interesting"
    },
    {
        "agents": [],
        "jobs": [],
        "id": 2,
        "tag": "boring"
    }
]

Statuscode 200:	no error

methods = ['GET', 'POST']¶

post()[source]¶

A POST to this endpoint will do one of two things:

• create a new tag and return the row
• return the row for an existing tag

Tags only have one column, the tag name. Two tags are automatically considered equal if the tag names are equal.

POST /api/v1/tags/ HTTP/1.1¶

Request

POST /api/v1/tags/ HTTP/1.1
Accept: application/json

{
    "tag": "interesting"
}

Response (new tag create)

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "tag": "interesting"
}

Request

POST /api/v1/tags/ HTTP/1.1
Accept: application/json

{
    "tag": "interesting"
}

Response (existing tag returned)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "tag": "interesting"
}

Statuscode 200:	an existing tag was found and returned
Statuscode 201:	a new tag was created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)

pyfarm.master.api.tags.schema()[source]¶

Returns the basic schema of Tag

GET /api/v1/tags/schema/ HTTP/1.1¶

Request

GET /api/v1/tags/schema/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "INTEGER",
    "tag": "VARCHAR(64)"
}

Statuscode 200:	no error

This module defines an API for managing and querying logs belonging to tasks

class pyfarm.master.api.tasklogs.LogsInTaskAttemptsIndexAPI[source]¶

Bases: flask.views.MethodView

get(job_id, task_id, attempt)[source]¶

A GET to this endpoint will return a list of all known logs that are associated with this attempt at running this task

GET /api/v1/jobs/<job_id>/tasks/<task_id>/attempts/<attempt>/logs/ HTTP/1.1¶

Request

GET /api/v1/jobs/4/tasks/1300/attempts/5/logs/ HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "agent_id": "3087ada4-290a-45b0-8c1a-21db4cd284fc",
        "created_on": "2014-09-03T10:58:59.754880",
        "identifier": "2014-09-03_10-58-59_4_4ee02475335911e4a935c86000cbf5fb.csv"
    }
]

Statuscode 200:	no error
Statuscode 404:	the specified task was not found

methods = ['GET', 'POST']¶

post(job_id, task_id, attempt)[source]¶

A POST to this endpoint will register a new logfile with the given attempt at running the given task

A logfile has an identifier which must be unique in the system. If two tasks get assigned a logfile with the same id, it is considered to be the same log.

POST /api/v1/jobs/<job_id>/tasks/<task_id>/attempts/<attempt>/logs/ HTTP/1.1¶

Request

POST /api/v1/jobs/4/tasks/1300/attempts/5/logs/ HTTP/1.1
Content-Type: application/json

{
    "identifier": "2014-09-03_10-58-59_4_4ee02475335911e4a935c86000cbf5fb.csv",
    "agent_id": "2dc2cb5a-35da-41d6-8864-329c0d7d5391"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "identifier": "2014-09-03_10-58-59_4_4ee02475335911e4a935c86000cbf5fb.csv",
    "agent_id": "2dc2cb5a-35da-41d6-8864-329c0d7d5391",
    "created_on": "2014-09-03T10:59:05.103005",
    "id": 148
}

Statuscode 201:	the association between this task attempt and logfile has been created
Statuscode 400:	there was something wrong with the request (such as invalid columns being included)
Statuscode 404:	the specified task does not exist
Statuscode 409:	the specified log was already registered on the specified task

class pyfarm.master.api.tasklogs.SingleLogInTaskAttempt[source]¶

Bases: flask.views.MethodView

get(job_id, task_id, attempt, log_identifier)[source]¶

A GET to this endpoint will return metadata about the specified logfile

GET /api/v1/jobs/<job_id>/tasks/<task_id>/attempts/<attempt>/logs/<log_identifier> HTTP/1.1¶

Request

GET /api/v1/jobs/4/tasks/1300/attempts/5/logs/2014-09-03_10-58-59_4_4ee02475335911e4a935c86000cbf5fb.csv HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 147,
    "identifier": "2014-09-03_10-58-59_4_4ee02475335911e4a935c86000cbf5fb.csv",
    "created_on": "2014-09-03T10:58:59.754880",
    "agent_id": "836ce137-6ad4-443f-abb9-94c4465ff87c"
}

Statuscode 200:	no error
Statuscode 404:	task or logfile not found

methods = ['GET']¶