From ff2e4c97160fbbb42a1f6de4ef5186963d262f15 Mon Sep 17 00:00:00 2001 From: Richard Eckart de Castilho Date: Tue, 19 Mar 2024 18:33:50 +0100 Subject: [PATCH] No issue: Rename command to inception-cli, convert README file to Markdown, fix warning --- README.md | 138 ++++++++++++++++++++++++++++++++++++++++++++ README.rst | 152 ------------------------------------------------- poetry.lock | 2 +- pyproject.toml | 4 +- 4 files changed, 141 insertions(+), 155 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..aba7fa1 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +# inception-cli + +*Command line tool for INCEpTION.* + +## Purpose + +This project provides a command line tool for the INCEpTION text +annotation platform which allows you to import, export and delete +projects. + +## Installation + +So far, the INCEpTION command line tool is not available from Pypi, but +you can still install it using pip directly from this GitHub repository +using the following command: + +``` shell +$ pip install -U git+https://github.com/inception-project/inception-cli.git +``` + +## Prepare INCEpTION to be able to use the Remote API + +- enable the remote API + - go to INCEpTIONs home folder + - open INCEpTIONs `settings.properties` file + - add the line `remote-api.enabled=true` + - restart INCEpTION + - now it should be possible to assign the role `ROLE_REMOTE` to a user +- create a remote-api user + - got to the user management page + - create a new user, e.g. `remote-api` + - assign at least the roles `ROLE_ADMIN`, `ROLE_USER` and `ROLE_REMOTE` + - make sure that the new user is enabled + - click on `Save` + +## Usage + +Run it from the command line to get a list of the available commands: + +``` shell +$ inception-cli project +``` + +All commands require the following options: + +- `-u`, `--url`.: INCEpTION instance URL +- `-U`, `--user`: User name of the previously created user, you + will be prompted to enter the password + +If you do not want to enter this information multiple times, just set +the environment variables `INCEPTION_USERNAME` and +`INCEPTION_PASSWORD`according to the previously created user in the +console session where you invoke the CLI. You can also set the INCEpTION +instance url by the environment variable `INCEPTION_HOST`. + +### delete + +Deletes the given projects. + +Options: + +- `--regex` (default=`False`): Whether to interpret the project name + as a regular expression +- `--dry-run` (default=`False`): Whether log actions would be + performed without performing them +- `--projects`: Names / regular expression of the projects which + should be deleted + +### export + +Exports projects and saves them to disk. + +Options: + +- `--regex` (default=`False`): Whether to interpret the project name + as a regular expression +- `--dry-run` (default=`False`): Whether log actions would be + performed without performing them +- `-o`, `--out` (default=`.`): Where the exported projects + should be saved +- `--projects`: Names / regular expression of the projects which + should be exported + +### import + +Imports the given projects. + +Options: + +- `--projects`: Names of the zip-files which should be imported + +### list + +Lists the projects. + + +## Migrating projects from WebAnno to INCEpTION + +- Enable the remote API in WebAnno + - go to WebAnno's home folder + - open WebAnno's `settings.properties` file + - add the line `remote-api.enabled=true` + - restart WebAnno + - now it should be possible to assign the role `ROLE_REMOTE` to a user +- Create a remote-api user in WebAnno + - got to the user management page + - create a new user, e.g. call it `remote-api` + - assign at least the roles `ROLE_ADMIN`, `ROLE_USER` and `ROLE_REMOTE` + - make sure that the new user is enabled + - click on **Save** +- Export all projects from WebAnno using inception-cli + - install inception-cli + ``` shell + $ pip install -U git+https://github.com/inception-project/inception-cli.git + ``` + - export all projects from WebAnno (replace WEBANNO_URL and WEBANNO_REMOTE_API_USERNAME with the url of your WebAnno instance and the name of the user created in step 2.) + ``` shell + $ inception-cli project export -u WEBANNO_URL -U WEBANNO_REMOTE_API_USERNAME --regex '.*' + ``` + - enter the password of the remote API user you created in WebAnno when asked + - `inception-cli` creates one zip-file for each exported project in the current directory +- Enable the remote API in INCEpTION + - go to INCEpTION's home folder + - open INCEpTION's `settings.properties` file + - add the line `remote-api.enabled=true` + - restart INCEpTION + - now it should be possible to assign the role `ROLE_REMOTE` to a user +- Create a remote-api user in INCEpTION + - got to the user management page + - create a new user, e.g. call it `remote-api` + - assign at least the roles `ROLE_ADMIN`, `ROLE_USER` and `ROLE_REMOTE` + - make sure that the new user is enabled + - click on **Save** +- Import all exported projects to INCEpTION using inception-cli (replace WEBANNO_URL and WEBANNO_REMOTE_API_USERNAME with the url of your WebAnno instance and the name of the user created in step 2) + - make sure the folder does not contain any zip-files which are no exported WebAnno-projects + ``` shell + $ inception-cli project import -u INCEPTION_URL -U INCEPTION_REMOTE_API_USERNAME --regex '*.zip' + ``` diff --git a/README.rst b/README.rst deleted file mode 100644 index 168ef3a..0000000 --- a/README.rst +++ /dev/null @@ -1,152 +0,0 @@ -inception-cli -============= - -*Command line tool for INCEpTION.* - - -Purpose -------- - -This project provides a command line tool for the INCEpTION text annotation platform which allows -you to import, export and delete projects. - - -Installation ------------- - -So far, the INCEpTION command line tool is not available from Pypi, but you can still -install it using pip directly from this GitHub repository using the following command: - -.. code:: shell - - $ pip install -U git+https://github.com/inception-project/inception-cli.git - - -Prepare INCEpTION to be able to use the Remote API --------------------------------------------------- - -- enable the remote API - - go to INCEpTIONs home folder - - open INCEpTIONs `settings.properties` file - - add the line ``remote-api.enabled=true`` - - restart INCEpTION - - now it should be possible to assign the role `ROLE_REMOTE` to a user -- create a remote-api user - - got to the user management page - - create a new user, e.g. remote-api - - assign at least the roles ``ROLE_ADMIN``, ``ROLE_USER`` and ``ROLE_REMOTE`` - - make sure that the new user is enabled - - click on ``Save`` - -Usage ------ - -Run it from the command line to get a list of the available commands: - -.. code:: shell - - $ inception project - -All commands require the following options: - -- "-u", "--url" INCEpTION instance URL -- "-U", "--user" User name of the previously created user, you will be prompted to enter the password - -If you do not want to enter this information multiple times, just set the environment variables -``INCEPTION_USERNAME`` and ``INCEPTION_PASSWORD``according to the previously created user in the -console session where you invoke the CLI. -You can also set the INCEpTION instance url by the environment variable ``INCEPTION_HOST``. - -delete -^^^^^^ -Deletes the given projects. - -Options: - -- "-u", "--url" INCEpTION instance URL -- "-U", "--user" User name of the previously created user, you will be prompted to enter the password -- "--regex" (default=False) Whether to interpret the project name as a regular expression -- "--dry-run" (default=False) Whether log actions would be performed without performing them -- "--projects" Names / regular expression of the projects which should be deleted - -export -^^^^^^ -Exports projects and saves them to disk. - -Options: - -- "-u", "--url" INCEpTION instance URL -- "-U", "--user" User name of the previously created user, you will be prompted to enter the password -- "--regex" (default=False) Whether to interpret the project name as a regular expression -- "--dry-run" (default=False) Whether log actions would be performed without performing them -- "-o", "--out" (default=".") Where the exported projects should be saved -- "--projects" Names / regular expression of the projects which should be exported - -import -^^^^^^ -Imports the given projects. - -Options: - -- "-u", "--url" INCEpTION instance URL -- "-U", "--user" User name of the previously created user, you will be prompted to enter the password -- "--regex" (default=False) Whether to interpret the project name as a regular expression -- "--projects" Names / regular expression of the zip-files which should be imported - - -list -^^^^ -Lists the projects. - -Options: - -- "-u", "--url" INCEpTION instance URL -- "-U", "--user" User name of the previously created user, you will be prompted to enter the password - - - -Use inception-cli to easily migrate from WebAnno to INCEpTION -------------------------------------------------------------- - -1. Enable the remote API in WebAnno - - go to WebAnnos home folder - - open WebAnnos `settings.properties` file - - add the line ``remote-api.enabled=true`` - - restart WebAnno - - now it should be possible to assign the role `ROLE_REMOTE` to a user -2. Create a remote-api user in WebAnno - - got to the user management page - - create a new user, e.g. remote-api - - assign at least the roles ``ROLE_ADMIN``, ``ROLE_USER`` and ``ROLE_REMOTE`` - - make sure that the new user is enabled - - click on ``Save`` -3. Export all projects from WebAnno using inception-cli - - install inception-cli - .. code:: shell - - $ pip install -U git+https://github.com/inception-project/inception-cli.git - - export all projects from WebAnno (replace WEBANNO_URL and WEBANNO_REMOTE_API_USERNAME with the url of your WebAnno instance and the name of the user created in step 2.) - .. code:: shell - - $ python inception project export -u WEBANNO_URL -U WEBANNO_REMOTE_API_USERNAME --regex .* - - enter the password of the user created in step 2. when asked - - inception-cli creates one zip-file for each exported project in the current directory -#. Enable the remote API in INCEpTION - - go to INCEpTIONs home folder - - open INCEpTIONs `settings.properties` file - - add the line ``remote-api.enabled=true`` - - restart INCEpTION - - now it should be possible to assign the role `ROLE_REMOTE` to a user -#. Create a remote-api user in INCEpTION - - got to the user management page - - create a new user, e.g. remote-api - - assign at least the roles ``ROLE_ADMIN``, ``ROLE_USER`` and ``ROLE_REMOTE`` - - make sure that the new user is enabled - - click on ``Save`` -#. Import all exported projects to INCEpTION using inception-cli - - go to the directory containing all exported projects - - make sure the folder does not contain any zip-files which are no exported WebAnno-projects - - import the exported projects (replace WEBANNO_URL and WEBANNO_REMOTE_API_USERNAME with the url of your WebAnno instance and the name of the user created in step 2): - .. code:: shell - - $ python inception project export -u INCEPTION_URL -U INCEPTION_REMOTE_API_USERNAME --regex *.zip diff --git a/poetry.lock b/poetry.lock index 4a7194f..55cdf88 100644 --- a/poetry.lock +++ b/poetry.lock @@ -898,4 +898,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = "^3.8" -content-hash = "b3d2c96011fa690c46fb5d3927487aa97cf109fd171c65a4945e663adf0fd210" +content-hash = "e2d01b2b090670dc900c71076184e8459c717042a4b901cbc1033d4a790d0c8c" diff --git a/pyproject.toml b/pyproject.toml index 20856a3..c7b1158 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,7 +16,7 @@ pytest = "^7.2" pytest-mock = "*" requests-mock = "*" flake8 = "*" -black = { version = "*", allows-prereleases = true } +black = { version = "*", allow-prereleases = true } coverage = "*" mkdocs = "^1.0" pytest-cov = "^3.0" @@ -32,7 +32,7 @@ line-length = 120 target_version = ['py38'] [tool.poetry.plugins."console_scripts"] -inception = "inception.cli:cli" +inception-cli = "inception.cli:cli" [build-system] requires = ["poetry_core>=1.0.0"]