# open-groceries
Unified data acquisition across multiple grocery store sites
## Installation
```bash
python3 -m pip install open-groceries
```
## Example Usage
```python
from open_groceries import OpenGrocery
# Initialize adapter clients
client = OpenGrocery()
# Print locations near Times Square
print(client.locations("Times Square NYC"))
# Print search results for "beans"
print(client.search("beans"))
# Print search suggestions for "pot"
print(client.suggest("pot"))
```
## API Documentation
**OpenGrocery:**
The OpenGrocery class is an aggregator for all included adapters. Function/constructor signatures are as follows:
- `OpenGrocery(features = ..., user_agent = ..., adapter_kwargs = ...)`
- `features`: Optional `str[]`, list of adapter names to initialize.
- `user_agent`: Optional `str`, user-agent string to pass to APIs.
- `adapter_kwargs`: Optional `{str: {str: any}}`, mapping of `adapter:{kwargs}` for individual adapter kwargs
- `OpenGrocery().locations(near, include = ...) -> Location[]`: Fetches locations near an address
- `near`: Required `str`, address to query.
- Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`
- `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized
- Returns `Location[]` in order of distance to specified address
- `OpenGrocery().set_nearest_stores(near, include = ...) -> None`: Sets each adapter to its nearest store
- `near`: Required `str`, address to query.
- Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`
- `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized
- `OpenGrocery().set_locations(locations) -> None`: Sets each adapter to a specific store
- `locations`: Required `{str: Location}`, mapping of adapter name to desired location. This function does not check whether the input location is valid for that adapter.
- `OpenGrocery().search(query, include = ...) -> GroceryItem[]`: Searches adapters for a search query
- `query`: Required `str`, search term to look for
- `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized
- Returns `GroceryItem[]` in order of similarity to the search term
- `OpenGrocery().adapter(adapter) -> GroceryAdapter | None`: Utility function to return an initialized adapter
- `adapter`: Required `str`, name of adapter to get
- Returns specified `GroceryAdapter` if found, or `None` if not
- `OpenGrocery().suggest(term, include = ...) -> str[]`: Gets autocompletion suggestions to search term
- `term`: Required `str`, search term to suggest for
- `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized
- Returns `str[]` in order of similarity to search term
**GroceryAdapter:**
The GroceryAdapter class is the abstract parent of all included Adapters. It shoul not be initialized itself, but should instead be subclassed to create Adapters.
- `GroceryAdapter(user_agent = ...)`
- `user_agent`: Optional `str`, user agent header to send to APIs
- `GroceryAdapter().search_groceries(search) -> GroceryItem[]`: Search for groceries
- `search`: Required `str`, search term to look for
- Returns `GroceryItem[]` in the order returned by the website
- `GroceryAdapter().get_grocery_item(id) -> GroceryItem`: Gets a specific grocery item by ID
- `id`: Required `str`, item ID to return
- Returns `GroceryItem` returned by the website
- `GroceryAdapter().get_locations(near) -> Location[]`: Gets store locations near an address
- `near`: Required `str`, address to query.
- Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`
- Returns `Location[]` in the order returned by the website
- `GroceryAdapter().set_location(location) -> None`: Sets preferred store location
- `location`: Required `Location`, location to set
- `GroceryAdapter().suggest(search) -> str[]`: Gets autocomplete suggestions for a search term
- `term`: Required `str`, search term to suggest for
- Returns `str[]` in order returned by the website
## Supported Stores
| Store | Item Search | Item Retrieval | Location Search | Location Filtering | Autocomplete |
| ------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------- |
| Wegmans | Full support [Long Term/Versioned API] | Full support [Long Term/Versioned API] | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Medium Term/External Versioned API] |
| Costco | Adequate support [Medium Term/Site Parsing] | Adequate support [Medium Term/Site Parsing] | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Long Term/Versioned API] |
Raw data
{
"_id": null,
"home_page": "https://github.com/iTecAI/open-groceries",
"name": "open-groceries",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "requests,modular,groceries,web,web scraping",
"author": "Dax Harris",
"author_email": "matteovh@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/03/942d05c3295c52f648f29827c0dfe2a4544b8b924225c3b0d50ca19624ab/open_groceries-0.3.2.tar.gz",
"platform": null,
"description": "# open-groceries\n\nUnified data acquisition across multiple grocery store sites\n\n## Installation\n\n```bash\npython3 -m pip install open-groceries\n```\n\n## Example Usage\n\n```python\nfrom open_groceries import OpenGrocery\n\n# Initialize adapter clients\nclient = OpenGrocery()\n\n# Print locations near Times Square\nprint(client.locations(\"Times Square NYC\"))\n\n# Print search results for \"beans\"\nprint(client.search(\"beans\"))\n\n# Print search suggestions for \"pot\"\nprint(client.suggest(\"pot\"))\n```\n\n## API Documentation\n\n**OpenGrocery:**\n\nThe OpenGrocery class is an aggregator for all included adapters. Function/constructor signatures are as follows:\n\n- `OpenGrocery(features = ..., user_agent = ..., adapter_kwargs = ...)`\n\n - `features`: Optional `str[]`, list of adapter names to initialize.\n - `user_agent`: Optional `str`, user-agent string to pass to APIs.\n - `adapter_kwargs`: Optional `{str: {str: any}}`, mapping of `adapter:{kwargs}` for individual adapter kwargs\n- `OpenGrocery().locations(near, include = ...) -> Location[]`: Fetches locations near an address\n\n - `near`: Required `str`, address to query.\n - Example formats: `\"14620\"`, `\"Times Square NYC\"`, `\"Rochester Institute of Technology\"`\n - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized\n - Returns `Location[]` in order of distance to specified address\n- `OpenGrocery().set_nearest_stores(near, include = ...) -> None`: Sets each adapter to its nearest store\n\n - `near`: Required `str`, address to query.\n - Example formats: `\"14620\"`, `\"Times Square NYC\"`, `\"Rochester Institute of Technology\"`\n - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized\n- `OpenGrocery().set_locations(locations) -> None`: Sets each adapter to a specific store\n\n - `locations`: Required `{str: Location}`, mapping of adapter name to desired location. This function does not check whether the input location is valid for that adapter.\n- `OpenGrocery().search(query, include = ...) -> GroceryItem[]`: Searches adapters for a search query\n\n - `query`: Required `str`, search term to look for\n - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized\n - Returns `GroceryItem[]` in order of similarity to the search term\n- `OpenGrocery().adapter(adapter) -> GroceryAdapter | None`: Utility function to return an initialized adapter\n\n - `adapter`: Required `str`, name of adapter to get\n - Returns specified `GroceryAdapter` if found, or `None` if not\n- `OpenGrocery().suggest(term, include = ...) -> str[]`: Gets autocompletion suggestions to search term\n\n - `term`: Required `str`, search term to suggest for\n - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized\n - Returns `str[]` in order of similarity to search term\n\n**GroceryAdapter:**\n\nThe GroceryAdapter class is the abstract parent of all included Adapters. It shoul not be initialized itself, but should instead be subclassed to create Adapters.\n\n- `GroceryAdapter(user_agent = ...)`\n\n - `user_agent`: Optional `str`, user agent header to send to APIs\n- `GroceryAdapter().search_groceries(search) -> GroceryItem[]`: Search for groceries\n\n - `search`: Required `str`, search term to look for\n - Returns `GroceryItem[]` in the order returned by the website\n- `GroceryAdapter().get_grocery_item(id) -> GroceryItem`: Gets a specific grocery item by ID\n\n - `id`: Required `str`, item ID to return\n - Returns `GroceryItem` returned by the website\n- `GroceryAdapter().get_locations(near) -> Location[]`: Gets store locations near an address\n\n - `near`: Required `str`, address to query.\n - Example formats: `\"14620\"`, `\"Times Square NYC\"`, `\"Rochester Institute of Technology\"`\n - Returns `Location[]` in the order returned by the website\n- `GroceryAdapter().set_location(location) -> None`: Sets preferred store location\n\n - `location`: Required `Location`, location to set\n- `GroceryAdapter().suggest(search) -> str[]`: Gets autocomplete suggestions for a search term\n\n - `term`: Required `str`, search term to suggest for\n - Returns `str[]` in order returned by the website\n\n## Supported Stores\n\n| Store | Item Search | Item Retrieval | Location Search | Location Filtering | Autocomplete |\n| ------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------- |\n| Wegmans | Full support [Long Term/Versioned API] | Full support [Long Term/Versioned API] | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Medium Term/External Versioned API] |\n| Costco | Adequate support [Medium Term/Site Parsing] | Adequate support [Medium Term/Site Parsing] | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Long Term/Versioned API] |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Unified data acquisition across multiple grocery store sites",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/iTecAI/open-groceries",
"Repository": "https://github.com/iTecAI/open-groceries"
},
"split_keywords": [
"requests",
"modular",
"groceries",
"web",
"web scraping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "712f9a8880c530ad56a2d023a5d35b669f71a079a36eeb2934f03bfd450ee098",
"md5": "ebc02bf46241c2143b21a0b8d9479382",
"sha256": "2750ed0bb5dbfbc4f7eaed1b74a022f0159d544f96af9d41f402320b3f68aaf5"
},
"downloads": -1,
"filename": "open_groceries-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebc02bf46241c2143b21a0b8d9479382",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 13587,
"upload_time": "2023-12-05T17:05:49",
"upload_time_iso_8601": "2023-12-05T17:05:49.656101Z",
"url": "https://files.pythonhosted.org/packages/71/2f/9a8880c530ad56a2d023a5d35b669f71a079a36eeb2934f03bfd450ee098/open_groceries-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a103942d05c3295c52f648f29827c0dfe2a4544b8b924225c3b0d50ca19624ab",
"md5": "e8b5e4886cd4cc466db4be310a858f09",
"sha256": "27c85ad05fcd689030d8ef4449e91741a7e20835240a2d641a113c170fb82828"
},
"downloads": -1,
"filename": "open_groceries-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "e8b5e4886cd4cc466db4be310a858f09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 11549,
"upload_time": "2023-12-05T17:05:51",
"upload_time_iso_8601": "2023-12-05T17:05:51.678573Z",
"url": "https://files.pythonhosted.org/packages/a1/03/942d05c3295c52f648f29827c0dfe2a4544b8b924225c3b0d50ca19624ab/open_groceries-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-05 17:05:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iTecAI",
"github_project": "open-groceries",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "open-groceries"
}
JSON
