Swimlane Python

https://github.com/swimlane/swimlane-python
Admin
🐍 Official Python client for the Swimlane API
Tokens:77,670
Snippets:672
Trust Score:9.8
License:Apache-2.0
Update:3 days ago
Show doc for...
Tokens:
Raw
### Clone and install from Git

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/index.rst

Manually clones the repository, checks out a specific branch or release, and installs. Installing via Git installs a working version, intended for driver development only.

```default
git clone https://github.com/swimlane/swimlane-python
cd swimlane-python
git checkout <branch>
pip install .
```

--------------------------------

### Quick Start: Connect and Create Record

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/index.rst

Connects to the Swimlane API using the Swimlane client, retrieves an app by name, creates a new record with various field types, and demonstrates field value access and modification. The example shows both connecting outside of Swimlane and from a Python task inside Swimlane.

```python
from swimlane import Swimlane


# Connect Swimlane client outside of Swimlane
swimlane = Swimlane('https://192.168.1.1', 'username', 'password')

# Connect Swimlane client from Python task in Swimlane
swimlane = Swimlane(sw_context.config['InternalSwimlaneUrl'],'username','password')


# Retrieve App by name
app = swimlane.apps.get(name='Target App')


# Create new Record
new_record = app.records.create(**{
    'Text Field': 'String',
    'Numeric Field': 100,
    'UserGroup Field': swimlane.user,
    'ValuesList Field': ['Option 1', 'Option 2']
})


# Work with field values
assert new_record['Text Field'] == 'String'

new_record['Numeric Field'] += 100
assert new_record['Numeric Field'] == 200

assert new_record['UserGroup Field'].id == swimlane.user.id
```

--------------------------------

### Install swimlane package from public repository

Source: https://github.com/swimlane/swimlane-python/blob/master/README.rst

Install the swimlane package from the public PyPI repository using pip.

```bash
pip install swimlane
```

--------------------------------

### Download and run offline installer

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/index.rst

Downloads the self-extracting .pyz archive from the GitHub releases page and runs it. Requires pip v9+; installation fails with earlier versions.

```default
wget https://github.com/swimlane/swimlane-python/releases/download/<release>/swimlane-python-<version>-offline-installer-<platform>-<python>.pyz
python ./swimlane-python-<version>-offline-installer-<platform>-<python>.pyz
```

--------------------------------

### Run offline installer for swimlane

Source: https://github.com/swimlane/swimlane-python/blob/master/README.rst

Run the offline installer with bundled dependencies for the specified platform and Python version.

```bash
python swimlane-python-offline-installer-<platform>-<python_version>.pyz
```

--------------------------------

### Client setup with personal access token

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Uses a personal access token instead of username and password for authentication.

```python
from swimlane import Swimlane

swimlane = Swimlane('192.168.1.1', access_token='abcdefg')
```

--------------------------------

### Get list of all apps

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the apps adapter to retrieve all App resources.

```python
apps = swimlane.apps.list()
```

--------------------------------

### Install functional test requirements

Source: https://github.com/swimlane/swimlane-python/blob/master/README.rst

Install the required PIP packages for running functional tests from the functional_tests directory.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install or upgrade Swimlane Python via pip

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/index.rst

Recommended installation method. Installs or upgrades the swimlane package to the latest release.

```default
pip install -U swimlane
```

--------------------------------

### Get list of all users

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the users adapter to retrieve all User resources.

```python
users = swimlane.users.list()
```

--------------------------------

### AppRevisionAdapter.get_all()

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.app_revision.md

Gets all app revisions for the adapter's app. Returns a list of AppRevision objects.

```APIDOC
## AppRevisionAdapter.get_all()

### Description
Gets all app revisions for the adapter's app.

### Method
GET (conceptual)

### Parameters
None

### Returns
- **AppRevision[]** - Returns all AppRevisions for this Adapter's app.

```

--------------------------------

### Minimal client setup with username and password

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Connects to a Swimlane server using host, username, and password. HTTPS is the default scheme if none is provided. Authentication is immediate and fails if credentials are invalid.

```python
from swimlane import Swimlane

swimlane = Swimlane('192.168.1.1', 'username', 'password')
```

--------------------------------

### Apps Adapter - get

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Retrieves an App resource by ID or name.

```APIDOC
## Apps Adapter - get

### Description
Retrieves an App resource by ID or name.

### Method
GET

### Endpoint
`swimlane.apps.get(id='...')` or `swimlane.apps.get(name='...')`

### Parameters
- **id** (string) - Optional - The ID of the app to retrieve.
- **name** (string) - Optional - The name of the app to retrieve.

### Request Example
```python
app_by_id = swimlane.apps.get(id='58f...387')
app_by_name = swimlane.apps.get(name='Target App')
```

### Response
Returns an App resource instance.
```

--------------------------------

### get_package_version()

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.utils.version.md

Returns the installed version of the swimlane package, or a development placeholder if not fully installed.

```APIDOC
## get_package_version()

### Description
Retrieves the installed swimlane package version. If the package is not fully installed, returns '0.0.0.dev'.

### Method
Function

### Signature
`get_package_version()`

### Parameters
None

### Returns
- **str** - Installed swimlane lib package version, or 0.0.0.dev if not fully installed
```

--------------------------------

### Get list of all groups

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the groups adapter to retrieve all Group resources.

```python
groups = swimlane.groups.list()
```

--------------------------------

### Search with Pagination Parameters

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Use page_start and page_end with limit=0 to retrieve a range of pages. This example retrieves pages 5 to 8 inclusive, containing records 501 to 900.

```python
# retrieve all results
records = app.records.search(
    ('Text Field', 'equals', 'value'),
    ...
    limit=0,
    page_size=100
    page_start=5,
    page_end=8
)
```

--------------------------------

### Retrieve an app by ID or name

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the apps adapter to get a single App resource by its ID or name.

```python
app_by_id = swimlane.apps.get(id='58f...387')

app_by_name = swimlane.apps.get(name='Target App')
```

--------------------------------

### Enable resource caching

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Enables caching for App, Record, User, and Group resources by setting resource_cache_size. Cache uses LFU eviction. The example also enables debug logging and shows a loop that benefits from caching.

```python
# Enable basic logging to print requests and cache hits/misses
import logging; logging.basicConfig(level=logging.DEBUG)

from swimlane import Swimlane

# Enable caching up to 20 different instances of each supported resource type
swimlane = Swimlane(
    '192.168.1.1',
    'username',
    'password',
    resource_cache_size=20
)

# Slow code making multiple requests for the same App, Record, and referenced Records in a loop
# With caching enabled, performance is much higher as requests are sent only for resources not already in the cache
for _ in range(5):
    app = swimlane.apps.get(id='abc...123')
    print(app)

    record = app.records.get(id='def...456')
    print(record)

    for reference_record in record['Reference Field']:
        print(reference_record)
```

--------------------------------

### Retrieve app revisions

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Gets all revisions, a specific revision by number, and the historical version of the app.

```python
# get all revisions
app_revisions = app.revisions.get_all()

# get by revision number
app_revision = app.revisions.get(2)

# get the historical version of the app
historical_app_version = app_revision.version
```

--------------------------------

### Users Adapter - get

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Retrieves a single User resource by ID or display name.

```APIDOC
## Users Adapter - get

### Description
Retrieves a single User resource by ID or display name.

### Method
GET

### Endpoint
`swimlane.users.get(id='...')` or `swimlane.users.get(display_name='...')`

### Parameters
- **id** (string) - Optional - The ID of the user to retrieve.
- **display_name** (string) - Optional - The display name of the user to retrieve.

### Request Example
```python
user_by_id = swimlane.users.get(id='58f...387')
user_by_display_name = swimlane.users.get(display_name='admin')
```

### Response
Returns a User resource instance.
```

--------------------------------

### TaskAdapter.get(key, value)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.task.md

Gets a single task by id or name.

```APIDOC
## TaskAdapter.get(key, value)

### Description
Gets a single task by id or name.

### Method
get

### Parameters
- **key** (str) - Required - The key to search by (e.g., 'id' or 'name').
- **value** (str) - Required - The value to match.

### Returns
The matching Task resource.
```

--------------------------------

### Retrieve a user by ID or display name

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the users adapter to get a single User resource by its ID or display name.

```python
user_by_id = swimlane.users.get(id='58f...387')

user_by_display_name = swimlane.users.get(display_name='admin')
```

--------------------------------

### Check bulk job status with helpers

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the helpers adapter to check the status of app.records.bulk_modify() or app.records.bulk_delete() jobs. The example shows a bulk modify operation and then checks its status, printing the job status output.

```python
# Get target app
app = swimlane.apps.get(name='App')

# Bulk modify records matching filters
job_id = app.records.bulk_modify(
    ('Numeric', 'equals', 1),
    values={'Numeric': 2}
)

# Check bulk job status
status = swimlane.helpers.check_bulk_job_status(job_id)
print(status)
```

```python
[{'$type': 'Core.Models.Jobs.JobInfo, Core',
  'job': 'a4EDVRY7UOHpz5_xV',
  'status': 'started',
  'task': 'BatchRecordUpdate'},
 {'$type': 'Core.Models.Jobs.JobInfo, Core',
  'job': 'a4EDVRY7UOHpz5_xV',
  'message': 'Batch update 100% completed.',
  'status': 'inProgress',
  'task': 'BatchRecordUpdate'},
 {'$type': 'Core.Models.Jobs.JobInfo, Core',
  'details': {'$type': 'Core.Models.Notifications.BulkModifyFinishedNotification, Core',
   'applicationId': 'aRDyEl8ZRd7gKrEN5',
   'bulkModificationType': 'update',
   'dateTime': '2018-01-02T16:46:46.4982709Z',
   'disabled': False,
   'errors': [],
   'id': 'aJxpdAwvKWUSaEPRz',
   'jobId': 'a4EDVRY7UOHpz5_xV',
   'notificationType': 'console',
   'output': 'Task complete',
   'status': 'Finished',
   'taskName': 'BatchRecordUpdate',
   'totalRecordsSkipped': 1,
   'totalRecordsUpdated': 0,
   'userName': 'admin',
   'warnings': [{'$type': 'Core.Models.Notifications.RecordMessage, Core',
     'message': 'Record is already locked, skipping',
     'recordId': 'aPieydMqIo6lgwxd9',
     'trackingId': 'BNAW-15'}]},
  'job': 'a4EDVRY7UOHpz5_xV',
  'status': 'completed',
  'task': 'BatchRecordUpdate'}]
```

--------------------------------

### DatetimeField - Date & Time

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates how to get and set a Date & Time field, which returns pendulum.DateTime instances. Includes warnings about nanosecond precision and equality comparisons.

```APIDOC
## DatetimeField - Date & Time

### Description
Full specific date & time field. Returns `pendulum.DateTime` instances.

### Usage

```python
datetime_field_value = record['Datetime']

# Drop-in replacement and extension of Python's builtin datetime
assert isinstance(datetime_field_value, datetime.datetime)
assert isinstance(datetime_field_value, pendulum.Pendulum)

assert datetime_field_value.year == 2017
assert datetime_field_value.month == 4
assert datetime_field_value.day == 10
assert datetime_field_value.hour == 16

# Set to a datetime/pendulum instance
# See warning below
record['Datetime'] = now = pendulum.now().replace(microseconds=0)

# Fail on generic timestamp/string (not enough context to guarantee consistent behavior)
try:
    record['Datetime'] = '2017-05-11 11:10:09'
except ValidationError:
    pass

assert record['Datetime'] == now
```

### Warning
Mongo only supports millisecond resolution, datetimes returned from Swimlane API lose nanosecond resolution, leading to potentially slightly inconsistent datetimes before and after saving a record.

For consistency, nanoseconds are automatically stripped from datetimes when the field is set to a datetime with nanosecond precision.

Field equality comparisons with pendulum.now() or other datetime instances with nanosecond resolution will not be accurate unless the nanoseconds are manually removed from the compared datetime.

```python
# 2017-09-20 12:34:56.987654
now = pendulum.now()

# 2017-09-20 12:34:56.987000
record['Datetime'] = now

assert record['Datetime'] != now
```

For guaranteed equality checks, simplest solution is to remove the microsecond component entirely when setting the field value in cases where sub-second resolution isn’t important.

```python
# 2017-09-20 12:34:56.000000
now = pendulum.now().replace(microsecond=0)

# 2017-09-20 12:34:56.000000
record['Datetime'] = now

assert record['Datetime'] == now
```

Manual rounding or less/greater than comparisons are necessary in cases where millisecond resolution is necessary

```python
## Rounding comparison

# 2017-09-20 12:34:56.987654
now = pendulum.now()

# 2017-09-20 12:34:56.987000
record['Datetime'] = now

# 2017-09-20 12:34:56.987000
rounded_now = now.replace(
    microsecond=math.floor(now.microsecond / 1000) * 1000
)

assert record['Datetime'] == rounded_now


## Proximity comparison

# 0.000654
assert abs((record['Datetime'] - now).total_seconds()) < 0.001
```
```

--------------------------------

### Search Records with Filters

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Use app.records.search with filter tuples of (field_name, filter_operator, field_value) that are AND'ed together. The example shows filters for text, date, multi-select, and reference fields.

```python
records = app.records.search(
    ('Text Field', 'equals', 'value'),
    ('Date Field', 'lessThan', pendulum.now()),
    ('Values List (Multi-Select)', 'equals', ['Option 1', 'Option 2'])
    ('Reference (Single-Select)', 'equals', target_record)
)
```

--------------------------------

### Retrieve record revisions

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Use record.revisions.get_all() to fetch all revisions, record.revisions.get(2) to fetch a specific revision by number, and record_revision.version to get the historical version of the record, which automatically retrieves the corresponding app revision.

```python
# get all revisions
record_revisions = record.revisions.get_all()

# get by revision number
record_revision = record.revisions.get(2)

# get the historical version of the app
# automatically retrieves the corresponding app revision to create the Record object
historical_record_version = record_revision.version
```

--------------------------------

### get

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record.md

Gets a single record by id or tracking_id. Supports resource cache.

```APIDOC
## get

### Description
Get a single record by id. Supports resource cache. Added option to retrieve record by tracking_id in version 2.17.0.

### Method
get

### Parameters
#### Keyword Arguments
- **id** (str) - Required - Full record ID
- **tracking_id** (str) - Optional - Record Tracking ID

### Response
#### Success Response
- **Record** (Record) - Matching Record instance returned from API

### Raises
- **TypeError** – No id argument provided
- **ValueError** – The lookup value is empty or None
```

--------------------------------

### Swimlane(host, username=None, password=None, verify_ssl=True, default_timeout=60, verify_server_version=True, resource_cache_size=0, access_token=None, write_to_read_only=False, retry=True, max_retries=5, retry_interval=5, headers=None, proxies=None)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.client.md

Initializes a new Swimlane client instance. This is the core class used throughout the library for all API requests and server interactions.

```APIDOC
## Swimlane(host, username=None, password=None, verify_ssl=True, default_timeout=60, verify_server_version=True, resource_cache_size=0, access_token=None, write_to_read_only=False, retry=True, max_retries=5, retry_interval=5, headers=None, proxies=None)

### Description
Initializes a new Swimlane client instance. This is the core class used throughout the library for all API requests and server interactions.

### Parameters
- **host** (str) - Required - Full RFC-1738 URL pointing to Swimlane host. Defaults will be provided for all parts.
- **username** (str) - Optional - Authentication username.
- **password** (str) - Optional - Authentication password.
- **verify_ssl** (bool) - Optional - Verify SSL (ignored on HTTP). Disable to use self-signed certificates.
- **default_timeout** (int) - Optional - Default request connect and read timeout in seconds for all requests.
- **verify_server_version** (bool) - Optional - Verify server version has same major version as client package. May require additional requests, set False to disable check.
- **resource_cache_size** (int) - Optional - Maximum number of each resource type to keep in memory cache. Set 0 to disable caching. Disabled by default.
- **access_token** (str) - Optional - Authentication token, used in lieu of a username and password.
- **write_to_read_only** (bool) - Optional - Enable the ability to write to Read-only fields.
- **retry** (bool) - Optional - Retry request when error code is >= 500.
- **max_retries** (int) - Optional - Maximum number of retry attempts.
- **retry_interval** (int) - Optional - Time interval (in seconds) between two retry attempts.
- **headers** (dict) - Optional - Additional headers to include in requests.
- **proxies** (dict) - Optional - Proxy configuration for requests.

### Example
```python
# Establish connection using username password
swimlane = Swimlane(
    'https://192.168.1.1',
    'username',
    'password',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)

# Or establish connection using personal access token
swimlane = Swimlane(
    'https://192.168.1.1',
    access_token='abcdefg',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)
```
```

--------------------------------

### Establish connection and retrieve an app

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.client.md

Shows how to create a Swimlane client using username/password or a personal access token, with optional SSL verification, custom headers, and proxies. Then retrieves an app by name.

```python
# Establish connection using username password
swimlane = Swimlane(
    'https://192.168.1.1',
    'username',
    'password',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)

# Or establish connection using personal access token
swimlane = Swimlane(
    'https://192.168.1.1',
    access_token='abcdefg',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)

# Retrieve an app
app = swimlane.apps.get(name='Target App')
```

--------------------------------

### Record.get_field(field_name)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.record.md

Gets the field instance used to get, set, and serialize internal field value.

```APIDOC
## Record.get_field(field_name)

### Description
Gets the field instance used to get, set, and serialize internal field value.

### Parameters
- **field_name** (str) - Required - Field name or key to retrieve

### Returns
- **Field** - Requested field instance

### Raises
- **UnknownField** - Raised if field_name not found in parent App

```

--------------------------------

### AppAdapter.list()

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.app.md

Retrieves a list of all apps available on the server.

```APIDOC
## AppAdapter.list()

### Description
Retrieve list of all apps.

### Method
GET

### Endpoint
Not specified

### Parameters
None

### Returns
- **list** of **App** - List of all retrieved apps
```

--------------------------------

### Swimlane Client Initialization with proxies

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Initializes the Swimlane client with proxy settings for all requests.

```APIDOC
## Swimlane Client Initialization with proxies

### Description
Initializes the Swimlane client with a dictionary of proxies to be used for all requests made by the client, including those made by preconfigured adapters.

### Method
Constructor

### Endpoint
`Swimlane(host, username, password, proxies={...})`

### Parameters
#### Constructor Parameters
- **host** (string) - Required - IP address or hostname of the Swimlane server.
- **username** (string) - Required - Username for authentication.
- **password** (string) - Required - Password for authentication.
- **proxies** (dict) - Optional - Dictionary mapping protocols to proxy URLs.

### Request Example
```python
from swimlane import Swimlane

swimlane = Swimlane(
    '192.168.1.1',
    'username',
    'password',
    proxies={
        'http': 'http://10.10.1.10:3128',
        'https': 'http://10.10.1.10:1080'
    }
)
```

### Response
No direct response; the client is initialized with the specified proxies.
```

--------------------------------

### Nanosecond precision loss warning example

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates that setting a datetime with nanoseconds results in a different value when read back due to MongoDB's millisecond resolution. The example shows that record['Datetime'] != now when now has microseconds.

```python
# 2017-09-20 12:34:56.987654
now = pendulum.now()

# 2017-09-20 12:34:56.987000
record['Datetime'] = now

assert record['Datetime'] != now
```

--------------------------------

### RevisionBase.version (property)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.revision_base.md

Gets the version of this revision.

```APIDOC
## RevisionBase.version (property)

### Description
Gets the version of this revision.

### Property
version

### Returns
- **int** - The version number.
```

--------------------------------

### Run all tests against a specific URL

Source: https://github.com/swimlane/swimlane-python/blob/master/README.rst

Run all tests against the server at 10.20.30.40.

```bash
pytest --url "https://10.20.30.40"
```

--------------------------------

### RevisionBase.user (property)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.revision_base.md

Gets the user that saved this revision.

```APIDOC
## RevisionBase.user (property)

### Description
Gets the user that saved this revision.

### Property
user

### Returns
- **User** - The user that saved this revision.
```

--------------------------------

### create

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record.md

Creates a new record on an app with simple or complex field names. Returns the newly created Record instance.

```APIDOC
## create

### Description
Creates a new record on an app with simple or complex field names.

### Method
create

### Parameters
#### Keyword Arguments
- **field_a** (any) - Required - Field value for simple field name
- **someOtherField** (any) - Required - Field value for simple field name
- **Field 1** (any) - Required - Field value for complex field name (use **kwargs)
- **Field 2** (any) - Required - Field value for complex field name (use **kwargs)

### Request Example
```default
record = app.records.create(
    field_a='Some Value',
    someOtherField=100,
    ...
)
```

```default
record = app.records.create(**{
    'Field 1': 'Field 1 Value',
    'Field 2': 100,
    ...
})
```

### Response
#### Success Response
- **Record** (Record) - Newly created Record instance with data as returned from API response

#### Response Example
```default
record = app.records.create(...)
```

### Raises
- **swimlane.exceptions.UnknownField** – If any fields are provided that are not available on target app
- **swimlane.exceptions.ValidationError** – If any field fails validation before creation
```

--------------------------------

### RevisionBase.revision_number (property)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.revision_base.md

Gets the revision number of this revision.

```APIDOC
## RevisionBase.revision_number (property)

### Description
Gets the revision number of this revision.

### Property
revision_number

### Returns
- **int** - The revision number.
```

--------------------------------

### Full immediate retrieval of all records

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.report.md

Shows how to build a report, add a filter, and immediately retrieve all records by converting the report to a list.

```default
report = app.reports.build('new-report')
report.filter('field_1', 'doesNotEqual', 'value')

records = list(report)
```

--------------------------------

### RevisionBase.modified_date (property)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.revision_base.md

Gets the date this revision was created.

```APIDOC
## RevisionBase.modified_date (property)

### Description
Gets the date this revision was created.

### Property
modified_date

### Returns
- **datetime** - The date this revision was created.
```

--------------------------------

### Create a record with simple field names

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record.md

Creates a new record on an app using simple field names as keyword arguments. The record is created with the provided field values and returns a Record instance.

```python
record = app.records.create(
    field_a='Some Value',
    someOtherField=100,
    ...
)
```

--------------------------------

### Swimlane Client Initialization with verify_server_version

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Initializes the Swimlane client with server version verification disabled.

```APIDOC
## Swimlane Client Initialization with verify_server_version

### Description
Initializes the Swimlane client with `verify_server_version=False` to disable the automatic check that the major versions of server and client match. This may require an additional request to retrieve the server version.

### Method
Constructor

### Endpoint
`Swimlane(host, username, password, verify_server_version=False)`

### Parameters
#### Constructor Parameters
- **host** (string) - Required - IP address or hostname of the Swimlane server.
- **username** (string) - Required - Username for authentication.
- **password** (string) - Required - Password for authentication.
- **verify_server_version** (boolean) - Optional - When `False`, disables server version verification. Default is `True`.

### Request Example
```python
from swimlane import Swimlane

swimlane = Swimlane(
    '192.168.1.1',
    'username',
    'password',
    verify_server_version=False
)
```

### Response
No direct response; the client is initialized with verification disabled.
```

--------------------------------

### Groups Adapter - get

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Retrieves a single Group resource by ID or name.

```APIDOC
## Groups Adapter - get

### Description
Retrieves a single Group resource by ID or name.

### Method
GET

### Endpoint
`swimlane.groups.get(id='...')` or `swimlane.groups.get(name='...')`

### Parameters
- **id** (string) - Optional - The ID of the group to retrieve.
- **name** (string) - Optional - The name of the group to retrieve.

### Request Example
```python
group_by_id = swimlane.groups.get(id='58f...387')
group_by_display_name = swimlane.groups.get(name='Everyone')
```

### Response
Returns a Group resource instance.
```

--------------------------------

### ReportAdapter.build(name, **kwargs)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.report.md

Creates a new local Report instance for the adapter's App. Accepts a name and optional keyword arguments passed to the Report class.

```APIDOC
## ReportAdapter.build(name, **kwargs)

### Description
Report instance factory for the adapter's App. Creates a new local Report instance.

### Method
build

### Parameters
- **name** (str) - Required - New Report name
- **\*\*kwargs** - Optional - Extra keyword args passed to Report class

### Returns
- **Report** - Newly created local Report instance
```

--------------------------------

### Set User, Group, or UserGroup on UserGroupField

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates setting a UserGroupField to a User instance and verifying the assignment.

```python
assert isinstance(swimlane.user, User)

record['User'] = swimlane.user

assert record['User'] == swimlane.user
```

--------------------------------

### Users Adapter - list

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Retrieves a list of all User resources.

```APIDOC
## Users Adapter - list

### Description
Retrieves a list of all User resources.

### Method
GET

### Endpoint
`swimlane.users.list()`

### Request Example
```python
users = swimlane.users.list()
```

### Response
Returns a list of User resource instances.
```

--------------------------------

### RecordRevisionAdapter.get_all()

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record_revision.md

Gets all revisions for a single record. Returns a list of RecordRevision objects for the given record ID.

```APIDOC
## RecordRevisionAdapter.get_all()

### Description
Get all revisions for a single record.

### Method
get_all

### Parameters
None

### Returns
- **RecordRevision[]** - All record revisions for the given record ID.

### Return Type
[RecordRevision](swimlane.core.resources.record_revision.md#swimlane.core.resources.record_revision.RecordRevision)[]
```

--------------------------------

### Get Information About the Revision

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Retrieves a specific revision of an App or Record and provides access to its metadata and the versioned resource.

```APIDOC
## Get Information About the Revision

### Description
Retrieves a specific revision of an App or Record and provides access to its metadata and the versioned resource.

### Method
GET (SDK method: `app.revisions.get`)

### Endpoint
`app.revisions.get(revision_number)`

### Parameters
- **revision_number** (int) - Required - The revision number to retrieve.

### Response
#### Revision Object Attributes
- **modified_date** (datetime) - The date this revision was created.
- **revision_number** (int) - The revision number of this revision.
- **status** (str) - Indicates whether this revision is the current revision or a historical revision.
- **user** (User) - The user that saved this revision.
- **version** (App or Record) - Returns an App or Record object representing the revision depending on revision type.

#### Additional Functions
- **str(revision)** - Returns name of the revision and the revision number as a string.
- **revision.for_json** - Returns a dict containing `modifiedDate`, `revisionNumber`, and `user` keys/attribute values.

### Example
```python
revision = app.revisions.get(1)

revision.modified_date # The date this revision was created.
revision.revision_number # The revision number of this revision.
revision.status # Indicates whether this revision is the current revision or a historical revision.
revision.user # The user that saved this revision.

app = revision.version # returns an App or Record object representing the revision depending on revision type.

# additional functions
text = str(revision) # returns name of the revision and the revision number as a string
json = revision.for_json # returns a dict containing modifiedDate, revisionNumber, and user keys/attribute values
```
```

--------------------------------

### create(**fields)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record.md

Creates and returns a new record in the associated app. Field values are validated before sending the create request to the server.

```APIDOC
## create(**fields)

### Description
Create and return a new record in associated app and return the newly created Record instance. Field values are validated before sending create request to server.

### Method
create

### Parameters
- **\*\*fields** - Required - Field names and values to be validated and sent to server with create request

### Notes
Keyword arguments should be field names with their respective python values. Field values are validated before sending create request to server.
```

--------------------------------

### Retrieve a group by ID or name

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use the groups adapter to get a single Group resource by its ID or name.

```python
group_by_id = swimlane.groups.get(id='58f...387')

group_by_display_name = swimlane.groups.get(name='Everyone')
```

--------------------------------

### Proxies

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Use a proxy for all requests made by the client by providing a dictionary of proxies during client instantiation. The specified proxies are used for all requests, including those made by preconfigured adapters.

```python
from swimlane import Swimlane

swimlane = Swimlane(
    '192.168.1.1',  # IP address or hostname
    'username',
    'password',
    proxies={ 'http': 'http://10.10.1.10:3128', 'https': 'http://10.10.1.10:1080' }
)
```

--------------------------------

### Apps Adapter - list

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/client.rst

Retrieves a list of all App resources.

```APIDOC
## Apps Adapter - list

### Description
Retrieves a list of all App resources.

### Method
GET

### Endpoint
`swimlane.apps.list()`

### Request Example
```python
apps = swimlane.apps.list()
```

### Response
Returns a list of App resource instances.
```

--------------------------------

### Create a new record with app.records.create

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/resources.rst

Creates a new record using the app.records adapter. Field values must adhere to validation rules. Default selections in Selection Fields are applied unless overridden. The created record is returned after being persisted on the server.

```python
new_record = app.records.create(**{
    'Text Field': 'Field Value',
    'Numeric Field': 50,
    ...
})
```

--------------------------------

### DatetimeField - Timespan

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates how to get a Timespan field, which returns pendulum.Duration instances. Note that this subtype cannot handle datetime/Pendulum instances.

```APIDOC
## DatetimeField - Timespan

### Description
Time period (2 hours, 4 minutes, 15 seconds). Returns `pendulum.Duration` instances.

### Usage

```python
timespan_field = record['Timespan']
assert isinstance(timespan_field, datetime.timedelta)
assert isinstance(timespan_field, pendulum.Duration)
```

### Note
Only subtype that cannot handle datetime/Pendulum instances. Must use datetime.timedelta or pendulum.Duration instances instead.
```

--------------------------------

### Swimlane.__init__

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.md

Constructor for the Swimlane API client. Initializes the client with connection details, authentication, and configuration options.

```APIDOC
## Swimlane(host, username=None, password=None, verify_ssl=True, default_timeout=60, verify_server_version=True, resource_cache_size=0, access_token=None, write_to_read_only=False, retry=True, max_retries=5, retry_interval=5, headers=None, proxies=None)

### Description
Creates a new Swimlane API client instance. This is the core class used for all API requests and server interactions.

### Parameters
- **host** (str) - Required - Full RFC-1738 URL pointing to Swimlane host. Defaults will be provided for all parts.
- **username** (str) - Optional - Authentication username.
- **password** (str) - Optional - Authentication password.
- **verify_ssl** (bool) - Optional - Verify SSL (ignored on HTTP). Disable to use self-signed certificates.
- **default_timeout** (int) - Optional - Default request connect and read timeout in seconds for all requests.
- **verify_server_version** (bool) - Optional - Verify server version has same major version as client package. May require additional requests, set False to disable check.
- **resource_cache_size** (int) - Optional - Maximum number of each resource type to keep in memory cache. Set 0 to disable caching. Disabled by default.
- **access_token** (str) - Optional - Authentication token, used in lieu of a username and password.
- **write_to_read_only** (bool) - Optional - Enable the ability to write to Read-only fields.
- **retry** (bool) - Optional - Retry request when error code is >= 500.
- **max_retries** (int) - Optional - Maximum number of retry attempts.
- **retry_interval** (int) - Optional - Time interval (in seconds) between two retry attempts.
- **headers** (dict) - Optional - Additional headers to include in requests.
- **proxies** (dict) - Optional - Proxy configuration for requests.

### Example
```python
# Establish connection using username password
swimlane = Swimlane(
    'https://192.168.1.1',
    'username',
    'password',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)

# Or establish connection using personal access token
swimlane = Swimlane(
    'https://192.168.1.1',
    access_token='abcdefg',
    verify_ssl=False,
    headers={'Custom-Header': 'value'},
    proxies={'http': 'http://proxy.example.com:8080', 'https': 'https://proxy.example.com:8080'}
)
```
```

--------------------------------

### DatetimeField - Time

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates how to get and set a Time field, which returns pendulum.Time instances. Includes a warning about timezone handling.

```APIDOC
## DatetimeField - Time

### Description
Time of day with no date component (12:34:56). Returns `pendulum.Time` instances.

### Usage

```python
time_field = record['Time']
assert isinstance(time_field, datetime.time)
assert isinstance(time_field, pendulum.Time)

# Set to full datetime, date portion is dropped and Time instance is always returned
record['Time'] = pendulum.now()
assert isinstance(record['Time'], pendulum.Time)

# Set to just time
record['Time'] = pendulum.now().time()
assert isinstance(record['Time'], pendulum.Time)
```

### Warning
Time instances do not respect timezone information, and should always be provided in UTC.

Recommend using full Pendulum datetime instances when working with Time fields. When using full datetimes, the timezone is respected before dropping the date portion.
```

--------------------------------

### compare_versions(version_a, version_b, zerofill=False)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.utils.version.md

Compares two version strings and returns the direction of the comparison. Optionally zero-fills missing version sections.

```APIDOC
## compare_versions(version_a, version_b, zerofill=False)

### Description
Compares two version strings and returns an integer indicating the relative order. If zerofill is True, missing version sections are treated as 0; otherwise, sections not present in both versions are ignored.

### Method
Function

### Signature
`compare_versions(version_a, version_b, zerofill=False)`

### Parameters
- **version_a** (str) - Required - First version to compare
- **version_b** (str) - Required - Second version to compare
- **zerofill** (bool) - Optional - If True, treat any missing version sections as 0, otherwise ignore section. Defaults to False

### Returns
- **int** - 0 if equal, -1 if a > b, 1 if a < b

### Examples
```pycon
>>> compare_versions('2', '2') == 0
>>> compare_versions('2', '1') == -1
>>> compare_versions('2', '3') == 1
```

If zerofill is False (default), sections not included in both versions are ignored during comparison

```pycon
>>> compare_versions('2.13.2', '2.13') == 0
>>> compare_versions('2.13.2-1234', '3') == 1
```

If zerofill is True, any sections in one version not included in other version are set to 0

```pycon
>>> compare_versions('2.13.2', '2.13', True) == -1
>>> compare_versions('2.13.2-1234', '2.13.2', True) == -1
>>> compare_versions('2.13.2', '2.13.2', True) == 0
```
```

--------------------------------

### AppRevision.version property

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.app_revision.md

Returns an App from the _raw_version info in this app revision. Lazy loaded.

```APIDOC
## AppRevision.version (property)

### Description
Returns an App from the _raw_version info in this app revision. Lazy loaded. Overridden from base class.

### Returns
An App object.
```

--------------------------------

### DatetimeField - Date

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Demonstrates how to get and set a Date field, which returns pendulum.Date instances. Setting a full datetime drops the time component.

```APIDOC
## DatetimeField - Date

### Description
Date of year with no time component (2017-06-01). Returns `pendulum.Date` instances.

### Usage

```python
date_field = record['Date']
assert isinstance(date_field, datetime.date)
assert isinstance(date_field, pendulum.Date)

# Set to full datetime, time portion is dropped and Date instance is always returned
record['Date'] = pendulum.now()
assert isinstance(record['Date'], pendulum.Date)

# Set to just date
record['Date'] = pendulum.now().date()
assert isinstance(record['Date'], pendulum.Date)
```
```

--------------------------------

### App.get_field_definition_by_id(field_id)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.app.md

Gets the JSON field definition for a field matching the provided ID. Raises UnknownField if the field ID is not found in the App.

```APIDOC
## get_field_definition_by_id(field_id)

### Description
Get JSON field definition for field matching provided id.

### Method
get_field_definition_by_id

### Parameters
- **field_id** (str) - Required - Target field ID to get definition for

### Raises
- **swimlane.exceptions.UnknownField** - Raised when given a field ID not found in App

### Returns
Field metadata definition (dict)

```

--------------------------------

### UserAdapter.list(limit=None)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.usergroup.md

Retrieves all users. Returns a paginated cursor yielding User instances. Raises ValueError if limit is not of type integer or None.

```APIDOC
## UserAdapter.list(limit=None)

### Description
Retrieve all users.

### Method
GET

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **limit** (int) - Optional - Limit the number of users returned

### Returns
- **UserListCursor** - Paginated cursor yielding User instances

### Raises
- **ValueError** - If limit is not of type integer or None
```

--------------------------------

### Return all records from app

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.adapters.record.md

Returns all records from the app by setting limit to 0, which overrides the default limit.

```python
# Return all records from app
records = app.records.search(limit=0)
```

--------------------------------

### App.get_field_definition_by_name(field_name)

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/apidoc/swimlane.core.resources.app.md

Gets the JSON field definition for a field matching the provided name or key. Raises UnknownField if the field name is not found in the App.

```APIDOC
## get_field_definition_by_name(field_name)

### Description
Get JSON field definition for field matching provided name or key.

### Method
get_field_definition_by_name

### Parameters
- **field_name** (str) - Required - Target field name or key to get definition for

### Raises
- **swimlane.exceptions.UnknownField** - Raised when given a field name not found in App

### Returns
Field metadata definition (dict)

```

--------------------------------

### UserGroupField returns UserGroup instances

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Shows that accessing a UserGroupField returns a UserGroup instance, with example assertions on id and name, and comparison with a specific group.

```python
usergroup = record['Group']

assert isinstance(usergroup, UserGroup)
assert usergroup.id == '58de1d1c07637a0264c0ca71'
assert usergroup.name == 'Everyone'

# UserGroup comparisons with specific User/Group instances
assert usergroup == swimlane.groups.get(name='Everyone')
```

--------------------------------

### Iterate over ReferenceField

Source: https://github.com/swimlane/swimlane-python/blob/master/docs/examples/fields.rst

Access a reference field to get a ReferenceCursor, check its length, and iterate over it to retrieve Record instances. Orphaned references are ignored and removed during iteration.

```python
reference = record['Reference']
assert isinstance(reference, ReferenceCursor)

assert len(reference) == 3

for referenced_record in reference:
    assert isinstance(referenced_record, Record)
    assert referenced_record._app != app
    assert referenced_record._app == reference.target_app
```
Tokens:
Raw