ralph-malph


Nameralph-malph JSON
Version 5.0.1 PyPI version JSON
download
home_pageNone
SummaryRalph, the ultimate Learning Record Store (and more!) for your learning analytics.
upload_time2024-07-11 09:41:24
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseMIT License Copyright (c) 2020-present France Université Numérique Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords lrs analytics xapi open edx
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            
<p align="center">
  <a href="https://openfun.github.io/ralph"><img src="https://raw.githubusercontent.com/openfun/logos/main/ralph/ralph-color-dark.png" alt="Ralph logo" width="400"></a>
</p>

<p align="center">
    <em>Ralph, the ultimate Learning Record Store (and more!) for your learning analytics</em>
</p>

<p align="center">
<a href="https://circleci.com/gh/openfun/ralph/tree/main">
    <img src="https://img.shields.io/circleci/build/gh/openfun/ralph/main?label=Tests&logo=circleci" alt="Tests Status">
</a>
<a href="https://pypi.org/project/ralph-malph">
    <img src="https://img.shields.io/pypi/v/ralph-malph?label=PyPI+package" alt="PyPI package version">
</a>
<a href="https://pypi.org/project/ralph-malph">
    <img src="https://img.shields.io/pypi/pyversions/ralph-malph?label=Python" alt="Python versions supported">
</a>
<a href="https://hub.docker.com/r/fundocker/ralph/tags">
    <img src="https://img.shields.io/docker/v/fundocker/ralph/latest?label=Docker+image" alt="Docker image version">
</a>
<a href="https://hub.docker.com/r/openfuncharts/ralph/tags">
    <img src="https://img.shields.io/docker/v/openfuncharts/ralph?label=Helm+chart&color=blue" alt="Helm chart version">
</a>
<a href="https://discord.gg/vYx6YWxJCS">
    <img src="https://img.shields.io/discord/1082704478463082496?label=Discord&logo=discord&style=shield" alt="Discord">
</a>
</p>

---

**Documentation**: [https://openfun.github.io/ralph](https://openfun.github.io/ralph)

**Source Code**: [https://github.com/openfun/ralph](https://github.com/openfun/ralph)

---

Ralph is a toolbox for your learning analytics, it can be used as a:

- **[LRS](https://en.wikipedia.org/wiki/Learning_Record_Store)**, a HTTP API server to collect xAPI statements (learning events), following the [ADL LRS standard](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#partthree)
- **command-line interface** (CLI), to build data pipelines the UNIX-way™️,
- **library**, to fetch learning events from various backends, (de)serialize or
    convert them from and to various standard formats such as
    [xAPI](https://adlnet.gov/projects/xapi/), or
    [openedx](https://docs.openedx.org/en/latest/developers/references/internal_data_formats/tracking_logs/index) html

## ⚡️ Quick start guide: Run the LRS server

> Preliminary notes:
>
> 1. [`curl`](https://curl.se), [`jq`](https://stedolan.github.io/jq/) and
>    [`docker compose`](https://docs.docker.com/compose/) are required to run
>    some commands of this tutorial. Make sure they are installed first.
>
> 2. In order to run the Elasticsearch backend locally on GNU/Linux operating
>    systems, ensure that your virtual memory limits are not too low and
>    increase them (temporally) if needed by typing this command from your
>    terminal (as `root` or using `sudo`): `sysctl -w vm.max_map_count=262144`
>
> Reference:
> https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html

To bootstrap a test environment on your machine, clone this project first and
run the `bootstrap` Makefile target:

```bash
make bootstrap
```

This command will create required `.env` file (you may want to edit it for your
test environment), build the Ralph's Docker image and start a single node
Elasticsearch cluster _via_ Docker compose.

You can check the `elasticsearch` service status using the `status` helper:

```bash
make status # This is an alias for: docker compose ps
```

You may now start the LRS server using:

```bash
make run
```

The server should be up and running at
[http://localhost:8100](http://localhost:8100). You can check its status using
the heartbeat probe:

```bash
curl http://localhost:8100/__heartbeat__
```

The expected answer should be:

```json
{"database":"ok"}
```

If the database status is satisfying, you are now ready to send xAPI statements
to the LRS:

```bash
gunzip -c data/statements.json.gz | \
head -n 100 | \
jq -s . | \
curl -Lk \
    --user ralph:secret \
    -X POST \
    -H "Content-Type: application/json" \
    -d @- \
    http://localhost:8100/xAPI/statements/
```

The command above fetches one hundred (100) example xAPI statements from our
[Potsie](https://github.com/openfun/potsie) project and sends them to the LRS
using `curl`.

You can get them back from the LRS using `curl` to query the
`/xAPI/statements/` endpoint:

```bash
curl -s \
    --user ralph:secret \
    -H "Content-Type: application/json" \
    http://localhost:8100/xAPI/statements/ \ |
jq
```

> Note that using `jq` is optional in this case, it is used to improve response
> readability. It is not required to install it to run this snippet.

## ⚡️ Quick start guide: Manipulate data with the CLI

### With the Docker image

Ralph is distributed as a [Docker
image](https://hub.docker.com/repository/docker/fundocker/ralph). If
[Docker](https://docs.docker.com/get-docker/) is installed on your machine, it
can be pulled from DockerHub:

```bash
docker run --pull always --rm fundocker/ralph:latest ralph --help
```

### With the Python package

Ralph is distributed as a standard python package; it can be installed _via_
`pip` or any other python package manager (_e.g._ Poetry, Pipenv, etc.):

```bash
# Install the full package
pip install \
    ralph-malph[full]

# Install only the core package (library usage without backends, CLI and LRS)
pip install ralph-malph
```

If you installed the full package (including the CLI, LRS and supported
backends), the `ralph` command should be available in your `PATH`. Try to
invoke the program usage thanks to the `--help` flag:

```bash
ralph --help
```

You should see a list of available commands and global flags for `ralph`. Note
that each command has its own usage that can be invoked _via_:

```bash
ralph COMMAND --help
```

> You should substitute `COMMAND` by the target command, _e.g._ `list`, to see
> its usage.

## Migrating

Some major version changes require updating persistence layers. Check out the [migration guide](https://github.com/openfun/ralph/blob/main/UPGRADE.md) for more information.

## Contributing

This project is intended to be community-driven, so please, do not hesitate to
get in touch if you have any question related to our implementation or design
decisions.

We try to raise our code quality standards and expect contributors to follow
the recommendations from our
[handbook](https://handbook.openfun.fr).

## Useful commands


You can explore all available rules using:

```bash
make help
```
but here are some of them:

- Bootstrap the project: `make bootstrap`
- Run tests: `make test`
- Run all linters: `make lint`
- If you add new dependencies to the project, you will have to rebuild the Docker
image (and the development environment): `make down && make bootstrap`

## License

This work is released under the MIT License (see [LICENSE](./LICENSE.md)).

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ralph-malph",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "LRS, Analytics, xAPI, Open edX",
    "author": null,
    "author_email": "\"Open FUN (France Universit\u00e9 Num\u00e9rique)\" <fun.dev@fun-mooc.fr>",
    "download_url": "https://files.pythonhosted.org/packages/fb/8c/c1f63a976f0a28751a4727f2a601c71cb7336931598cff704305bf6a1772/ralph_malph-5.0.1.tar.gz",
    "platform": null,
    "description": "\n<p align=\"center\">\n  <a href=\"https://openfun.github.io/ralph\"><img src=\"https://raw.githubusercontent.com/openfun/logos/main/ralph/ralph-color-dark.png\" alt=\"Ralph logo\" width=\"400\"></a>\n</p>\n\n<p align=\"center\">\n    <em>Ralph, the ultimate Learning Record Store (and more!) for your learning analytics</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://circleci.com/gh/openfun/ralph/tree/main\">\n    <img src=\"https://img.shields.io/circleci/build/gh/openfun/ralph/main?label=Tests&logo=circleci\" alt=\"Tests Status\">\n</a>\n<a href=\"https://pypi.org/project/ralph-malph\">\n    <img src=\"https://img.shields.io/pypi/v/ralph-malph?label=PyPI+package\" alt=\"PyPI package version\">\n</a>\n<a href=\"https://pypi.org/project/ralph-malph\">\n    <img src=\"https://img.shields.io/pypi/pyversions/ralph-malph?label=Python\" alt=\"Python versions supported\">\n</a>\n<a href=\"https://hub.docker.com/r/fundocker/ralph/tags\">\n    <img src=\"https://img.shields.io/docker/v/fundocker/ralph/latest?label=Docker+image\" alt=\"Docker image version\">\n</a>\n<a href=\"https://hub.docker.com/r/openfuncharts/ralph/tags\">\n    <img src=\"https://img.shields.io/docker/v/openfuncharts/ralph?label=Helm+chart&color=blue\" alt=\"Helm chart version\">\n</a>\n<a href=\"https://discord.gg/vYx6YWxJCS\">\n    <img src=\"https://img.shields.io/discord/1082704478463082496?label=Discord&logo=discord&style=shield\" alt=\"Discord\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://openfun.github.io/ralph](https://openfun.github.io/ralph)\n\n**Source Code**: [https://github.com/openfun/ralph](https://github.com/openfun/ralph)\n\n---\n\nRalph is a toolbox for your learning analytics, it can be used as a:\n\n- **[LRS](https://en.wikipedia.org/wiki/Learning_Record_Store)**, a HTTP API server to collect xAPI statements (learning events), following the [ADL LRS standard](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#partthree)\n- **command-line interface** (CLI), to build data pipelines the UNIX-way\u2122\ufe0f,\n- **library**, to fetch learning events from various backends, (de)serialize or\n    convert them from and to various standard formats such as\n    [xAPI](https://adlnet.gov/projects/xapi/), or\n    [openedx](https://docs.openedx.org/en/latest/developers/references/internal_data_formats/tracking_logs/index) html\n\n## \u26a1\ufe0f Quick start guide: Run the LRS server\n\n> Preliminary notes:\n>\n> 1. [`curl`](https://curl.se), [`jq`](https://stedolan.github.io/jq/) and\n>    [`docker compose`](https://docs.docker.com/compose/) are required to run\n>    some commands of this tutorial. Make sure they are installed first.\n>\n> 2. In order to run the Elasticsearch backend locally on GNU/Linux operating\n>    systems, ensure that your virtual memory limits are not too low and\n>    increase them (temporally) if needed by typing this command from your\n>    terminal (as `root` or using `sudo`): `sysctl -w vm.max_map_count=262144`\n>\n> Reference:\n> https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html\n\nTo bootstrap a test environment on your machine, clone this project first and\nrun the `bootstrap` Makefile target:\n\n```bash\nmake bootstrap\n```\n\nThis command will create required `.env` file (you may want to edit it for your\ntest environment), build the Ralph's Docker image and start a single node\nElasticsearch cluster _via_ Docker compose.\n\nYou can check the `elasticsearch` service status using the `status` helper:\n\n```bash\nmake status # This is an alias for: docker compose ps\n```\n\nYou may now start the LRS server using:\n\n```bash\nmake run\n```\n\nThe server should be up and running at\n[http://localhost:8100](http://localhost:8100). You can check its status using\nthe heartbeat probe:\n\n```bash\ncurl http://localhost:8100/__heartbeat__\n```\n\nThe expected answer should be:\n\n```json\n{\"database\":\"ok\"}\n```\n\nIf the database status is satisfying, you are now ready to send xAPI statements\nto the LRS:\n\n```bash\ngunzip -c data/statements.json.gz | \\\nhead -n 100 | \\\njq -s . | \\\ncurl -Lk \\\n    --user ralph:secret \\\n    -X POST \\\n    -H \"Content-Type: application/json\" \\\n    -d @- \\\n    http://localhost:8100/xAPI/statements/\n```\n\nThe command above fetches one hundred (100) example xAPI statements from our\n[Potsie](https://github.com/openfun/potsie) project and sends them to the LRS\nusing `curl`.\n\nYou can get them back from the LRS using `curl` to query the\n`/xAPI/statements/` endpoint:\n\n```bash\ncurl -s \\\n    --user ralph:secret \\\n    -H \"Content-Type: application/json\" \\\n    http://localhost:8100/xAPI/statements/ \\ |\njq\n```\n\n> Note that using `jq` is optional in this case, it is used to improve response\n> readability. It is not required to install it to run this snippet.\n\n## \u26a1\ufe0f Quick start guide: Manipulate data with the CLI\n\n### With the Docker image\n\nRalph is distributed as a [Docker\nimage](https://hub.docker.com/repository/docker/fundocker/ralph). If\n[Docker](https://docs.docker.com/get-docker/) is installed on your machine, it\ncan be pulled from DockerHub:\n\n```bash\ndocker run --pull always --rm fundocker/ralph:latest ralph --help\n```\n\n### With the Python package\n\nRalph is distributed as a standard python package; it can be installed _via_\n`pip` or any other python package manager (_e.g._ Poetry, Pipenv, etc.):\n\n```bash\n# Install the full package\npip install \\\n    ralph-malph[full]\n\n# Install only the core package (library usage without backends, CLI and LRS)\npip install ralph-malph\n```\n\nIf you installed the full package (including the CLI, LRS and supported\nbackends), the `ralph` command should be available in your `PATH`. Try to\ninvoke the program usage thanks to the `--help` flag:\n\n```bash\nralph --help\n```\n\nYou should see a list of available commands and global flags for `ralph`. Note\nthat each command has its own usage that can be invoked _via_:\n\n```bash\nralph COMMAND --help\n```\n\n> You should substitute `COMMAND` by the target command, _e.g._ `list`, to see\n> its usage.\n\n## Migrating\n\nSome major version changes require updating persistence layers. Check out the [migration guide](https://github.com/openfun/ralph/blob/main/UPGRADE.md) for more information.\n\n## Contributing\n\nThis project is intended to be community-driven, so please, do not hesitate to\nget in touch if you have any question related to our implementation or design\ndecisions.\n\nWe try to raise our code quality standards and expect contributors to follow\nthe recommendations from our\n[handbook](https://handbook.openfun.fr).\n\n## Useful commands\n\n\nYou can explore all available rules using:\n\n```bash\nmake help\n```\nbut here are some of them:\n\n- Bootstrap the project: `make bootstrap`\n- Run tests: `make test`\n- Run all linters: `make lint`\n- If you add new dependencies to the project, you will have to rebuild the Docker\nimage (and the development environment): `make down && make bootstrap`\n\n## License\n\nThis work is released under the MIT License (see [LICENSE](./LICENSE.md)).\n",
    "bugtrack_url": null,
    "license": "MIT License  Copyright (c) 2020-present France Universit\u00e9 Num\u00e9rique  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
    "summary": "Ralph, the ultimate Learning Record Store (and more!) for your learning analytics.",
    "version": "5.0.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/openfun/ralph/issues",
        "Changelog": "https://github.com/openfun/ralph/blob/main/CHANGELOG.md",
        "Homepage": "https://openfun.github.io/ralph/",
        "Repository": "https://github.com/openfun/ralph"
    },
    "split_keywords": [
        "lrs",
        " analytics",
        " xapi",
        " open edx"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "51d2cd4cb5b74dc59bdce0a4ec8be4984109d687d2caad5debe9d96b6fb190d2",
                "md5": "6820cf4ad19e06398323c7e69521fa0e",
                "sha256": "cab766cb27e9356dca4db5773a02774c944ae61902c064e0c99cfd6bbbcf2d2a"
            },
            "downloads": -1,
            "filename": "ralph_malph-5.0.1-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6820cf4ad19e06398323c7e69521fa0e",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=3.8",
            "size": 201079,
            "upload_time": "2024-07-11T09:41:22",
            "upload_time_iso_8601": "2024-07-11T09:41:22.493585Z",
            "url": "https://files.pythonhosted.org/packages/51/d2/cd4cb5b74dc59bdce0a4ec8be4984109d687d2caad5debe9d96b6fb190d2/ralph_malph-5.0.1-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "fb8cc1f63a976f0a28751a4727f2a601c71cb7336931598cff704305bf6a1772",
                "md5": "a19ff76ecfa7386e41772992d4d0857a",
                "sha256": "5f59cce1dea95a9895e2d7536ca070fb0543515b7f3a6ded8ec45b4085a932fd"
            },
            "downloads": -1,
            "filename": "ralph_malph-5.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "a19ff76ecfa7386e41772992d4d0857a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 145783,
            "upload_time": "2024-07-11T09:41:24",
            "upload_time_iso_8601": "2024-07-11T09:41:24.082149Z",
            "url": "https://files.pythonhosted.org/packages/fb/8c/c1f63a976f0a28751a4727f2a601c71cb7336931598cff704305bf6a1772/ralph_malph-5.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-07-11 09:41:24",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "openfun",
    "github_project": "ralph",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "circle": true,
    "lcname": "ralph-malph"
}
        
Elapsed time: 0.25578s