| Name | fractionalindex JSON |
| Version |
0.0.2
JSON |
| download |
| home_page | None |
| Summary | Fractional index library with multiple backends |
| upload_time | 2024-12-26 23:14:04 |
| maintainer | None |
| docs_url | None |
| author | Jeremy Howard |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FractionalIndex
## Overview
A `FractionalIndex` takes a list of existing items and allows you to insert a new item between any two existing items, or at the start or end.
Internally, it uses the `fractional_indexing` pypi package, which works as follows:
```python
first = generate_key_between(None, None) # 'a0'
second = generate_key_between(first, None) # 'a1' (after 1st)
third = generate_key_between(second, None) # 'a2' (after 2nd)
zeroth = generate_key_between(None, first) # 'Zz' (before 1st)
```
`FractionalIndex` differs with `fractional_indexing` in how it handles skipping the `before` or `after` parameters. If you only pass `before`, it will insert before the specified item, but after the largest item before that (if there is none, then it will insert at the start). If you only pass `after`, it will insert after the specified item, but before the smallest item after that (if there is none, then it will insert at the end).
```python
idx = FractionalIndex()
i1 = idx.insert() # starts a new index
print(i1) # 'a0'
i2 = idx.insert(after=i1) # inserts after i1
i3 = idx.insert(before=i2) # inserts before i2
i4 = idx.insert(i3, i2) # inserts between i3 and i2
i5 = idx.insert() # adds to the end
```
To add to the start, you can either pass the first item to `insert(before=...)`, or use `begin()`:
```python
i6 = idx.begin()
```
You can create an index from a list of existing items, which will be sorted:
```python
idx = FractionalIndex([i1, i2, i3, i4, i5, i6])
```
## Implementation
Internally, `FractionalIndex` by default uses `IndexingList`, a subclass of `sortedcontainers.SortedList` to store the items. The sort is needed so that `insert` without one of both of `after` or `before` can quickly find the next, previous or start/end item. The subclass adds the following methods (which are the only methods required by `FractionalIndex`):
- `after(item)`: returns the next item after the specified item, or `None` if there is none.
- `before(item)`: returns the previous item before the specified item, or `None` if there is none.
- `begin()`: returns the first item.
- `end()`: returns the last item.
## Alternative Implementations
FractionalIndex comes with a few alternative implementations.
### FileIndex
`FileIndex` uses `FileIndexing` instead of `IndexingList` internally. `FileIndexing` is a simple implementation which uses a list of files in a directory, to identify the correct locations in the index. For instance, consider the following directory contents:
```
a0-create-table.sql
a1-add-column.sql
a2-add-index.sql
```
In this case, we can create a suitable `FileIndex` with `idx = FileIndex(directory='.', separator='-')`. Since these are the default values, we can simply call `FileIndex()` to create it. Note that the directory will be re-scanned for the latest files on every method call.
You can then use it just like a regular FractionalIndex:
```python
idx = FileIndex(directory='migrations', separator='-')
new_id = idx.begin() # Creates ID before first file
new_id = idx.insert() # Creates ID after last file
new_id = idx.insert(after='a0') # Creates ID between a0 and next file
new_id = idx.insert(before='a1') # Creates ID between previous file and a1
new_id = idx.insert('a0', 'a1') # Creates ID between a0 and a1
```
When you get a new ID, you'll need to create the corresponding file (e.g., `{new_id}-something.sql`) for it to be included in future operations.
### SqliteIndex
`SqliteIndex` indexes a sqlite DB table by using the `SqliteIndexing` class. Generally, the fractional index will be the primary key of the table. To use it, you need to pass a `Connection`, `table` and `column` (defaults to 'id') to the constructor:
```python
import sqlite3
conn = sqlite3.connect("database.db")
conn.execute("CREATE TABLE migrations (id TEXT PRIMARY KEY)")
# Create the index
idx = SqliteIndex(conn, 'migrations', 'id')
# Use it like any other FractionalIndex
new_id = idx.begin() # Creates ID before first row
new_id = idx.insert() # Creates ID after last row
new_id = idx.insert(after='a0') # Creates ID between a0 and next row
new_id = idx.insert(before='a1') # Creates ID between previous row and a1
new_id = idx.insert('a0', 'a1') # Creates ID between a0 and a1
# Don't forget to insert the new ID into your table
conn.execute("INSERT INTO migrations (id) VALUES (?)", (new_id,))
conn.commit()
```
Note that SqliteIndex will query the database on every operation to ensure it's working with the latest data, but it won't automatically insert new IDs - you need to do that yourself after getting a new ID.
Raw data
{
"_id": null,
"home_page": null,
"name": "fractionalindex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Jeremy Howard",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cf/ef/420e56d2915e956d4383647a01f85923b3612d7913ff7eb9b1b1fcf7617f/fractionalindex-0.0.2.tar.gz",
"platform": null,
"description": "# FractionalIndex\n\n## Overview\n\nA `FractionalIndex` takes a list of existing items and allows you to insert a new item between any two existing items, or at the start or end.\n\nInternally, it uses the `fractional_indexing` pypi package, which works as follows:\n\n```python\nfirst = generate_key_between(None, None) # 'a0'\nsecond = generate_key_between(first, None) # 'a1' (after 1st)\nthird = generate_key_between(second, None) # 'a2' (after 2nd)\nzeroth = generate_key_between(None, first) # 'Zz' (before 1st)\n```\n\n`FractionalIndex` differs with `fractional_indexing` in how it handles skipping the `before` or `after` parameters. If you only pass `before`, it will insert before the specified item, but after the largest item before that (if there is none, then it will insert at the start). If you only pass `after`, it will insert after the specified item, but before the smallest item after that (if there is none, then it will insert at the end).\n\n```python\nidx = FractionalIndex()\ni1 = idx.insert() # starts a new index\nprint(i1) # 'a0'\ni2 = idx.insert(after=i1) # inserts after i1\ni3 = idx.insert(before=i2) # inserts before i2\ni4 = idx.insert(i3, i2) # inserts between i3 and i2\ni5 = idx.insert() # adds to the end\n```\n\nTo add to the start, you can either pass the first item to `insert(before=...)`, or use `begin()`:\n\n```python\ni6 = idx.begin()\n```\n\nYou can create an index from a list of existing items, which will be sorted:\n\n```python\nidx = FractionalIndex([i1, i2, i3, i4, i5, i6])\n```\n\n## Implementation\n\nInternally, `FractionalIndex` by default uses `IndexingList`, a subclass of `sortedcontainers.SortedList` to store the items. The sort is needed so that `insert` without one of both of `after` or `before` can quickly find the next, previous or start/end item. The subclass adds the following methods (which are the only methods required by `FractionalIndex`):\n\n- `after(item)`: returns the next item after the specified item, or `None` if there is none.\n- `before(item)`: returns the previous item before the specified item, or `None` if there is none.\n- `begin()`: returns the first item.\n- `end()`: returns the last item.\n\n## Alternative Implementations\n\nFractionalIndex comes with a few alternative implementations.\n\n### FileIndex\n\n`FileIndex` uses `FileIndexing` instead of `IndexingList` internally. `FileIndexing` is a simple implementation which uses a list of files in a directory, to identify the correct locations in the index. For instance, consider the following directory contents:\n\n```\na0-create-table.sql\na1-add-column.sql\na2-add-index.sql\n```\n\nIn this case, we can create a suitable `FileIndex` with `idx = FileIndex(directory='.', separator='-')`. Since these are the default values, we can simply call `FileIndex()` to create it. Note that the directory will be re-scanned for the latest files on every method call.\n\nYou can then use it just like a regular FractionalIndex:\n\n```python\nidx = FileIndex(directory='migrations', separator='-')\nnew_id = idx.begin() # Creates ID before first file\nnew_id = idx.insert() # Creates ID after last file\nnew_id = idx.insert(after='a0') # Creates ID between a0 and next file\nnew_id = idx.insert(before='a1') # Creates ID between previous file and a1\nnew_id = idx.insert('a0', 'a1') # Creates ID between a0 and a1\n```\n\nWhen you get a new ID, you'll need to create the corresponding file (e.g., `{new_id}-something.sql`) for it to be included in future operations.\n\n### SqliteIndex\n\n`SqliteIndex` indexes a sqlite DB table by using the `SqliteIndexing` class. Generally, the fractional index will be the primary key of the table. To use it, you need to pass a `Connection`, `table` and `column` (defaults to 'id') to the constructor:\n\n```python\nimport sqlite3\n\nconn = sqlite3.connect(\"database.db\")\nconn.execute(\"CREATE TABLE migrations (id TEXT PRIMARY KEY)\")\n\n# Create the index\nidx = SqliteIndex(conn, 'migrations', 'id')\n\n# Use it like any other FractionalIndex\nnew_id = idx.begin() # Creates ID before first row\nnew_id = idx.insert() # Creates ID after last row\nnew_id = idx.insert(after='a0') # Creates ID between a0 and next row\nnew_id = idx.insert(before='a1') # Creates ID between previous row and a1\nnew_id = idx.insert('a0', 'a1') # Creates ID between a0 and a1\n\n# Don't forget to insert the new ID into your table\nconn.execute(\"INSERT INTO migrations (id) VALUES (?)\", (new_id,))\nconn.commit()\n```\n\nNote that SqliteIndex will query the database on every operation to ensure it's working with the latest data, but it won't automatically insert new IDs - you need to do that yourself after getting a new ID.\n",
"bugtrack_url": null,
"license": null,
"summary": "Fractional index library with multiple backends",
"version": "0.0.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5c34ac30bbc98e39393c957cab3fcc5f7d6120b4b79dc34cbe61f7bebc22b43",
"md5": "885d8b731043b128448572daaa9dc61f",
"sha256": "8e6ada29b537808507659c44e7982eb38e8301e1717707f5ffd4aeb43095e4db"
},
"downloads": -1,
"filename": "fractionalindex-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "885d8b731043b128448572daaa9dc61f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8720,
"upload_time": "2024-12-26T23:14:02",
"upload_time_iso_8601": "2024-12-26T23:14:02.329215Z",
"url": "https://files.pythonhosted.org/packages/d5/c3/4ac30bbc98e39393c957cab3fcc5f7d6120b4b79dc34cbe61f7bebc22b43/fractionalindex-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfef420e56d2915e956d4383647a01f85923b3612d7913ff7eb9b1b1fcf7617f",
"md5": "603120cb73dd6368f7ea4abd79bbf9b9",
"sha256": "c976d20a3beed51192a1c3c619f67bbe96c03c070a670ed2541b21a577ec77db"
},
"downloads": -1,
"filename": "fractionalindex-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "603120cb73dd6368f7ea4abd79bbf9b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8937,
"upload_time": "2024-12-26T23:14:04",
"upload_time_iso_8601": "2024-12-26T23:14:04.557490Z",
"url": "https://files.pythonhosted.org/packages/cf/ef/420e56d2915e956d4383647a01f85923b3612d7913ff7eb9b1b1fcf7617f/fractionalindex-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-26 23:14:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "fractionalindex"
}
