Metadata-Version: 2.1
Name: udata-recommendations
Version: 3.1.7.dev772
Summary: uData content recommendations bridge
Home-page: https://github.com/opendatateam/udata-recommendations
Author: Opendata Team
Author-email: contact@opendata.team
License: LGPL
Keywords: udata recommendations
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Environment :: Web Environment
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Software Distribution
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: udata >=3.2.0
Requires-Dist: udata-front >=3.1.3
Requires-Dist: jsonschema >=3.2.0
Provides-Extra: test
Requires-Dist: pytest ==7.4.3 ; extra == 'test'
Requires-Dist: pytest-flask ==1.3.0 ; extra == 'test'
Requires-Dist: pytest-sugar ==0.9.7 ; extra == 'test'
Requires-Dist: requests-mock ==1.11.0 ; extra == 'test'
Requires-Dist: mock ==5.0.1 ; extra == 'test'
Requires-Dist: pytest-mock ==3.11.1 ; extra == 'test'

# udata-recommendations

This plugin acts as a bridge between uData and a recommendation system.

In our case ([data.gouv.fr][]), it's a set of scripts living here https://github.com/etalab/piwik-covisits.

Recommendations are stored on datasets. Recommendations can come from various sources and are stored in a descending order, according to the provided score (from 1 to 100). The top recommendations are displayed at the bottom on the dataset page.

## Compatibility

**udata-recommendations** requires Python 3.7+ and [uData][].

## Installation

Install [uData][].

Remain in the same virtual environment (for Python).

Install **udata-recommendations**:

```shell
pip install udata-recommendations
```

Modify your local configuration file of **udata** (typically, `udata.cfg`) as following:

```python
PLUGINS = ['recommendations']
RECOMMENDATIONS_SOURCES = {
    'source-name': 'https://path/to/recommendations.json',
    'other-source': 'https://path/to/other/recommendations.json',
}
RECOMMENDATIONS_NB_RECOMMENDATIONS = 4
```

- `RECOMMENDATIONS_SOURCES`: A key-value dictionary of recommendation sources and URLs to fetch. _Default_: `{}`
- `RECOMMENDATIONS_NB_RECOMMENDATIONS`: The maximum number of recommendations to display on the dataset page. _Default_: `4`

## Usage

### Adding recommendations

You can fetch and store recommendations as a task, using your configuration in `RECOMMENDATIONS_SOURCES`, on a schedule if needed. By default, previous recommendations are cleaned before the importing new ones, but you're in control.

```shell
udata job run recommendations-add
# Don't clean each source before importing new recommendations
udata job run recommendations-add should_clean=false
```

### Deleting recommendations

To clean all recommendations, you can run the following task.

```shell
udata job run recommendations-clean
```

## Expectations

This plugin expects the following format to provide datasets recommendations:

```json
[
  {
    "id": "dataset-id",
    "recommendations": [
      {
        "id": "dataset-slug-1",
        "score": 100
      },
      {
        "id": "5ef1fe80f50446b8f41ba691",
        "score": 1
      }
    ]
  },
  {
    "id": "dataset-id2",
    "recommendations": [
      {
        "id": "5ef1fe80f50446b8f41ba691",
        "score": 50
      }
    ]
  }
]
```

Dataset IDs can be IDs or slugs. Scores should be between `1` and `100`, inclusive. You can validate your JSON using a [JSON Schema](udata_recommendations/schema.json).

[uData]: https://github.com/opendatateam/udata
[data.gouv.fr]: https://data.gouv.fr

# Changelog

## Current (in progress)

- Nothing yet

## 3.1.6 (2024-07-30)

- Migrate to Python 3.11 following `udata` dependencies upgrade [#265](https://github.com/opendatateam/udata-recommendations/pull/265)
- Unpin jsonschema deps [#266](https://github.com/opendatateam/udata-recommendations/pull/266)

## 3.1.5 (2023-11-21)

- Update Matomo content tracking data-attributes [#263](https://github.com/opendatateam/udata-recommendations/pull/263)
- Upgrade test and develop dependencies [#264](https://github.com/opendatateam/udata-recommendations/pull/264)

## 3.1.4 (2023-03-07)

- Update and compile translations [#261](https://github.com/opendatateam/udata-recommendations/pull/261) [#262](https://github.com/opendatateam/udata-recommendations/pull/262)

## 3.1.3 (2023-03-02)

- Recommendations for new dataset page [#256](https://github.com/opendatateam/udata-recommendations/pull/256)

## 3.1.2 (2022-12-15)

- Update dataset and reuse recommendations to match new udata-front layout [207](https://github.com/opendatateam/udata-recommendations/pull/207)

## 3.1.1 (2022-09-01)

- Replace mongo legacy image in CI [#226](https://github.com/opendatateam/udata-recommendations/pull/226)
- Store unique recommendations in extras [#239](https://github.com/opendatateam/udata-recommendations/pull/239)

## 3.1.0 (2021-09-16)

- Change udata-gouvfr dependency to udata-front following renaming [#188](https://github.com/opendatateam/udata-recommendations/pull/188)

## 3.0.0 (2021-08-12)

- Ensure compatibility with udata3 by changing imports and style [#183](https://github.com/opendatateam/udata-recommendations/pull/183)

## 2.2.0 (2020-11-30)

- Add reuses support [#153](https://github.com/opendatateam/udata-recommendations/pull/153)

## 2.1.1 (2020-10-16)

- Ignore recommendation of dataset itself [#147](https://github.com/opendatateam/udata-recommendations/pull/147)

## 2.1.0 (2020-08-25)

- Add score to recommendations and support multiple recommendation sources [#142](https://github.com/opendatateam/udata-recommendations/pull/142)

## 2.0.0 (2020-03-11)

- udata 2.0 / Python 3 support [#95](https://github.com/opendatateam/udata-recommendations/pull/95)
- Support new hooks format [#96](https://github.com/opendatateam/udata-recommendations/pull/96)

## 1.0.1 (2018-08-03)

- Nothing yet

## 1.0.0 (2018-06-06)

- Allow slug instead of id for datasets [#8](https://github.com/opendatateam/udata-recommendations/pull/8)
- Initial release

