# Smartools
smartools is a wrapper around the official [smartsheet-python-sdk]. It monkey patches several classes to add new functionality, and also implements some completely new classes/models as well.
The decision was made to monkey patch the smartsheet sdk rather than fork it because by extending the existing package, this package can be updated independently of the original sdk and sis not dependent on a specific version.
## Installation
The package is available to install from [PyPi](https://pypi.org/project/smartools/) using:
```
pip install smartools
```
Once installed it can be imported with `import smartools` or can more "authentically" replace the official sdk by using `import smartools as smartsheet`
## Usage
In general, usage of smartools is identical to the standard SDK. All original functionality is supported so any existing code should not need to be updated. For more information, see the [Smartsheet API Docs](https://smartsheet.redoc.ly/).
## Extended/Improved Functionality
### Comparison of sharing permissions
smartools allows you to easily compare sharing permissions using the standard >, <, >=, >=, == methods. This can be useful when writing code that will evaluate whether a user has high enough permissions to perform an action. Smartools also has added support for the COMMENTER permission level. It also includes a new permission level, "UNSHARED" that can be used for comparisons. That permission level simply indicates that somethng isn't shared to you, and is only ever returned when using a `get_access_level` method.
```
sheet = smartsheet_client.Sheets.get_sheet(sheet_id)
sheet.access_level # EDITOR_SHARE
sheet.access_level >= 'EDITOR' # True
sheet.access_level == 'OWNER' # False
sheet.access_level > 'EDITOR' # True
sheet.access_level != 'UNSHARED' # True - This is a new "permission level" exclusive to smartools
```
### Easily Retrieve Child Rows
Rows now allow you to get their child rows by accessing row.children.
```
sheet = smartsheet_client.Sheets.get_sheet(sheet_id)
sheet.rows[0].children # Will return a list of child rows
```
### Indexing sheets/reports
Some of the greatest improvements to smartools are in the indexing of lists. Rows, Columns, and Cells can now be indexed using strings, as explained below.
#### Columns
Index a list of columns by utilizing the column name. You can also find the primary column with an empty string `''`. Indexing with integers (based on positioning) is still possible.
```
sheet = smartshet_client.Sheets.get_sheet(sheet_id)
sheet.columns['Date'].type # DATE
sheet.columns[''].primary # True
sheet.columns[3].title # Column4
```
#### Rows
Indexing rows can be done utilizing the primary column value or by using a tuple to specify the column that should be searched. Indexing with integers is still possible.
NOTE: If multiple rows have the same primary column value, the **first** row with this value will be returned. If indexing with an empty string `''` the first row with no primary column value will be returned.
```
sheet = smartsheet_client.Sheets.get_sheet(sheetid)
sheet.rows['Task Name'].id # 12345678910
```
#### Cells
Indexing a list of cells can be done utilizing column names. Indexing with integers is still possible.
NOTE: Indexing this way is only possible in requests where columns have been obtained, such as when getting a sheet or report, but will not work if columns are not included in the response, such as when getting a row.
```
sheet = smartsheet_client.Sheets.get_sheet(sheetid)
sheet.rows['Phase 1'].cells['Start Date'].value # 01/01/20222
```
### Getting Forms
Calling `get_sheet` with `include='publishedFormContainers'` will now include basic form information (such as its permalink) with the sheet.
## Brand New Functionality
### Cell Formatting
smartools includes a CellFormat model that allows you to apply formatting in a more user-friendly way. To use this, create a `CellFormat` object and update its various properties, such as `font_family`, `thousands_separator`, etc. A short usage example can be seen below, and a full list of all the properties that can be updated can be found [here](./docs/cell_format.md).
```
formatting = smartsheet.models.CellFormat()
formatting.font_type = 'TAHOMA'
formatting.font_size = 'TWELVE'
formatting.bold = 1 # Will apply the "1" setting of legacy formatting management using strings, which is "ON"
new_row = smartsheet.models.Row()
new_row.cells.append({
'column_id': 12345678910,
'value': 'My Value',
'format': formatting,
})
new_row.cells.append({
'column_id': 23456789101,
'value': 'My Other Value',
'format': smartsheet.models.CellFormat({
'italic': 'ON',
'strikethrough': 'ON',
'background_color': 'FFFEE6',
})
})
smartsheet_client.Sheets.add_rows(sheet_id, new_row)
```
### New methods
Several new methods have been added to the various classes within the smartsheet_client, these are listed below and documented in more detail within their respective docs.
### [Sheets](./docs/sheets.md)
- `Sheets.bulk_add_rows`
- `Sheets.bulk_update_rows`
- `Sheets.bulk_delete_rows`
- `Sheets.get_access_level`
### [Reports](./docs/reports.md)
- `Reports.update_report`
- `Reports.move_report`
- `Reports.get_large_report`
- `Reports.get_access_level`
### [Home](./docs/home.md)
- `Home.get_container_from_url`
- `Home.create_sight`
- `Home.create_report`
### [Folders](./docs/folders.md)
- `Folders.list_sheets_in_folder`
- `Folders.list_containers_in_folder`
- `Folders.get_access_level`
- `Folders.create_sight_in_folder`
- `Folders.create_report_in_folder`
### [Workspaces](./docs/workspaces.md)
- `Workspaces.list_sheets_in_workspace`
- `Workspaces.list_containers_in_workspace`
- `Workspaces.get_access_level`
- `Workspaces.create_sight_in_workspace`
- `Workspaces.create_report_in_workspace`
[smartsheet-python-sdk]: <https://github.com/smartsheet-platform/smartsheet-python-sdk>
Raw data
{
"_id": null,
"home_page": "https://github.com/davocarli",
"name": "smartools",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Smartsheet,smartsheet-python-sdk,monkey-patch",
"author": "David Carli-Arnold",
"author_email": "davocarli@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/49/e0/a6c269119b01402915270841db322ad7683cbc817890a2dae47d328b1e53/smartools-1.2.2.tar.gz",
"platform": null,
"description": "\n# Smartools\n\nsmartools is a wrapper around the official [smartsheet-python-sdk]. It monkey patches several classes to add new functionality, and also implements some completely new classes/models as well.\n\nThe decision was made to monkey patch the smartsheet sdk rather than fork it because by extending the existing package, this package can be updated independently of the original sdk and sis not dependent on a specific version.\n\n## Installation\nThe package is available to install from [PyPi](https://pypi.org/project/smartools/) using:\n```\npip install smartools\n```\nOnce installed it can be imported with `import smartools` or can more \"authentically\" replace the official sdk by using `import smartools as smartsheet`\n\n## Usage\nIn general, usage of smartools is identical to the standard SDK. All original functionality is supported so any existing code should not need to be updated. For more information, see the [Smartsheet API Docs](https://smartsheet.redoc.ly/).\n\n## Extended/Improved Functionality\n\n### Comparison of sharing permissions\nsmartools allows you to easily compare sharing permissions using the standard >, <, >=, >=, == methods. This can be useful when writing code that will evaluate whether a user has high enough permissions to perform an action. Smartools also has added support for the COMMENTER permission level. It also includes a new permission level, \"UNSHARED\" that can be used for comparisons. That permission level simply indicates that somethng isn't shared to you, and is only ever returned when using a `get_access_level` method.\n```\nsheet = smartsheet_client.Sheets.get_sheet(sheet_id)\n\nsheet.access_level # EDITOR_SHARE\nsheet.access_level >= 'EDITOR' # True\nsheet.access_level == 'OWNER' # False\nsheet.access_level > 'EDITOR' # True\nsheet.access_level != 'UNSHARED' # True - This is a new \"permission level\" exclusive to smartools\n```\n\n### Easily Retrieve Child Rows\nRows now allow you to get their child rows by accessing row.children.\n```\nsheet = smartsheet_client.Sheets.get_sheet(sheet_id)\n\nsheet.rows[0].children # Will return a list of child rows\n```\n\n### Indexing sheets/reports\nSome of the greatest improvements to smartools are in the indexing of lists. Rows, Columns, and Cells can now be indexed using strings, as explained below.\n\n#### Columns\nIndex a list of columns by utilizing the column name. You can also find the primary column with an empty string `''`. Indexing with integers (based on positioning) is still possible.\n```\nsheet = smartshet_client.Sheets.get_sheet(sheet_id)\n\nsheet.columns['Date'].type # DATE\nsheet.columns[''].primary # True\nsheet.columns[3].title # Column4\n```\n\n#### Rows\nIndexing rows can be done utilizing the primary column value or by using a tuple to specify the column that should be searched. Indexing with integers is still possible.\n\nNOTE: If multiple rows have the same primary column value, the **first** row with this value will be returned. If indexing with an empty string `''` the first row with no primary column value will be returned.\n```\nsheet = smartsheet_client.Sheets.get_sheet(sheetid)\n\nsheet.rows['Task Name'].id # 12345678910\n```\n\n#### Cells\nIndexing a list of cells can be done utilizing column names. Indexing with integers is still possible. \n\nNOTE: Indexing this way is only possible in requests where columns have been obtained, such as when getting a sheet or report, but will not work if columns are not included in the response, such as when getting a row.\n```\nsheet = smartsheet_client.Sheets.get_sheet(sheetid)\n\nsheet.rows['Phase 1'].cells['Start Date'].value # 01/01/20222\n```\n\n### Getting Forms\nCalling `get_sheet` with `include='publishedFormContainers'` will now include basic form information (such as its permalink) with the sheet.\n\n## Brand New Functionality\n\n### Cell Formatting\nsmartools includes a CellFormat model that allows you to apply formatting in a more user-friendly way. To use this, create a `CellFormat` object and update its various properties, such as `font_family`, `thousands_separator`, etc. A short usage example can be seen below, and a full list of all the properties that can be updated can be found [here](./docs/cell_format.md).\n```\nformatting = smartsheet.models.CellFormat()\nformatting.font_type = 'TAHOMA'\nformatting.font_size = 'TWELVE'\nformatting.bold = 1 # Will apply the \"1\" setting of legacy formatting management using strings, which is \"ON\"\n\nnew_row = smartsheet.models.Row()\nnew_row.cells.append({\n 'column_id': 12345678910,\n 'value': 'My Value',\n 'format': formatting,\n})\nnew_row.cells.append({\n 'column_id': 23456789101,\n 'value': 'My Other Value',\n 'format': smartsheet.models.CellFormat({\n 'italic': 'ON',\n 'strikethrough': 'ON',\n 'background_color': 'FFFEE6',\n })\n})\n\nsmartsheet_client.Sheets.add_rows(sheet_id, new_row)\n```\n\n### New methods\nSeveral new methods have been added to the various classes within the smartsheet_client, these are listed below and documented in more detail within their respective docs.\n### [Sheets](./docs/sheets.md)\n- `Sheets.bulk_add_rows`\n- `Sheets.bulk_update_rows`\n- `Sheets.bulk_delete_rows`\n- `Sheets.get_access_level`\n\n### [Reports](./docs/reports.md)\n- `Reports.update_report`\n- `Reports.move_report`\n- `Reports.get_large_report`\n- `Reports.get_access_level`\n\n### [Home](./docs/home.md)\n- `Home.get_container_from_url`\n- `Home.create_sight`\n- `Home.create_report`\n\n### [Folders](./docs/folders.md)\n- `Folders.list_sheets_in_folder`\n- `Folders.list_containers_in_folder`\n- `Folders.get_access_level`\n- `Folders.create_sight_in_folder`\n- `Folders.create_report_in_folder`\n\n### [Workspaces](./docs/workspaces.md)\n- `Workspaces.list_sheets_in_workspace`\n- `Workspaces.list_containers_in_workspace`\n- `Workspaces.get_access_level`\n- `Workspaces.create_sight_in_workspace`\n- `Workspaces.create_report_in_workspace`\n\n[smartsheet-python-sdk]: <https://github.com/smartsheet-platform/smartsheet-python-sdk>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A wrapper for the smartsheet-python-sdk that monkey-patches in new methods & functionality.",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/davocarli"
},
"split_keywords": [
"smartsheet",
"smartsheet-python-sdk",
"monkey-patch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "49e0a6c269119b01402915270841db322ad7683cbc817890a2dae47d328b1e53",
"md5": "f6e82181de85baa6273f8deedf2a63b0",
"sha256": "31f465a205a62a1145c28db58d5c7be5746b3ad4e4ae43b5d175009dc9c8bf0b"
},
"downloads": -1,
"filename": "smartools-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "f6e82181de85baa6273f8deedf2a63b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20494,
"upload_time": "2024-02-20T19:38:08",
"upload_time_iso_8601": "2024-02-20T19:38:08.604326Z",
"url": "https://files.pythonhosted.org/packages/49/e0/a6c269119b01402915270841db322ad7683cbc817890a2dae47d328b1e53/smartools-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-20 19:38:08",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "smartools"
}
JSON