From c43efe6a0d6826c04b32c1011bbcaa0167dcfca6 Mon Sep 17 00:00:00 2001 From: lxy2304 Date: Tue, 30 Jul 2024 00:16:46 -0400 Subject: [PATCH 1/5] Update documentation for v1.3 --- docs/source/changelog.rst | 6 ++ docs/source/conf.py | 13 ++--- docs/source/getting_started.rst | 100 ++++++++++---------------------- rtd_requirements.txt | 1 + 4 files changed, 41 insertions(+), 79 deletions(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index df95300c..c73c7166 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -3,6 +3,12 @@ Changelog ********* + +Version 1.3.0 +============= + +* Upgraded Neo4j compatibility to 5.x + Version 1.2.1 ============= diff --git a/docs/source/conf.py b/docs/source/conf.py index b5338e6e..c6fa745c 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,7 +15,7 @@ import sys import os - +from importlib.metadata import version as get_version import mock MOCK_MODULES = ['textgrid', 'textgrid.textgrid', @@ -97,14 +97,9 @@ copyright = '2015-2019, Montreal Corpus Tools' author = 'Montreal Corpus Tools' -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '{}.{}'.format(polyglotdb.__ver_major__, polyglotdb.__ver_minor__) -# The full version, including alpha/beta/rc tags. -release = polyglotdb.__version__ +release: str = get_version("polyglotdb") +# for example take major/minor +version: str = ".".join(release.split('.')[:2]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 2f166a09..85ad992d 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -2,6 +2,8 @@ .. _installation: +.. _Conda Installation: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html + *************** Getting started *************** @@ -25,42 +27,48 @@ dependencies that must be installed prior to using a Polyglot database, dependin Installation ============ +It is recommended to create an insolated conda environment for using PolyglotDB, for ensuring the correct Java version as well as better package management with Python. + +If you don't have conda installed on your device: + +#. Install either Anaconda, Miniconda, or Miniforge (`Conda Installation`_) +#. Make sure your conda is up to date :code:`conda update conda` + +.. note:: + On Windows, you should use Anaconda Prompt or Miniforge Prompt in order to use conda. + To install via pip: -``pip install polyglotdb`` +#. Create the a conda environment via :code:`conda create -n polyglotdb -c conda-forge openjdk pip` +#. Activate conda environment :code:`conda activate polyglotdb` +#. Install PolyglotDB via :code:`pip install polyglotdb`, which will install the ``pgdb`` utility that can be run inside your conda environment + and manages a local database. To install from source (primarily for development): #. Clone or download the Git repository (https://github.com/MontrealCorpusTools/PolyglotDB). -#. Navigate to the directory via command line and install the dependencies via :code:`pip install -r requirements.txt` -#. Install PolyglotDB via :code:`python setup.py install`, which will install the ``pgdb`` utility that can be run anywhere +#. Navigate to the directory via command line and create the conda environment via :code:`conda env create -f environment.yml` +#. Activate conda environment :code:`conda activate polyglotdb-dev` +#. Install PolyglotDB via :code:`pip install -e .`, which will install the ``pgdb`` utility that can be run inside your conda environment and manages a local database. -.. note:: - - The use of ``sudo`` is not recommended for installation. Ideally your Python installation should be managed by either - Anaconda or Homebrew (for Macs). - .. _local_setup: Set up local database --------------------- -Installing the PolyglotDB package also installs a utility script (``pgdb``) that is then callable from the command line -anywhere on the system. The ``pgdb`` command allows for the administration of a single Polyglot database (install/start/stop/uninstall). +Installing the PolyglotDB package also installs a utility script (``pgdb``) that is then callable from the command line inside your conda environment. +The ``pgdb`` command allows for the administration of a single Polyglot database (install/start/stop/uninstall). Using ``pgdb`` requires that several prerequisites be installed first, and the remainder of this section will detail how to install these on various platforms. Please be aware that using the ``pgdb`` utility to set up a database is not recommended for larger groups or those needing remote access. See the `ISCAN server`_ for a more fully featured solution. -Mac -``` - -#. Ensure Java 11 is installed inside Anaconda distribution (``conda install -c anaconda openjdk``) if using Anaconda, or - via Homebrew otherwise (``brew cask install java``) -#. Check Java version is 11 via ``java --version`` -#. Once PolyglotDB is installed, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or +Mac & Linux +``````````` +#. Make sure you are inside the dedicated conda environment just created. If not, activate it via :code:`conda activate polyglotdb` +#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or :code:`pgdb install` to save data in the default directory. .. warning:: @@ -75,66 +83,18 @@ To uninstall, run :code:`pgdb uninstall` Windows ``````` -#. Ensure Java 11 is installed (https://www.java.com/) and on the path (``java --version`` works in the command prompt) -#. Check Java version is 11 via ``java --version`` -#. Start an Administrator command prompt (right click on cmd.exe and select "Run as administrator"), as Neo4j will be installed as a Windows service. -#. Run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or +#. Make sure you are running as an Administrator (right-click on Anaconda Prompt/Miniforge Prompt and select "Run as administrator"), as Neo4j will be installed as a Windows service. +#. If you had to reopen a command prompt in Step 1, reactivate your conda environment via: :code:`conda activate polyglotdb`. +#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or :code:`pgdb install` to save data in the default directory. -To start the database, you likewise have to use an administrator command prompt before entering the commands :code:`pgdb start` +To start/stop the database, you likewise have to use an administrator command prompt before entering the commands :code:`pgdb start` or :code:`pgdb stop`. To uninstall, run :code:`pgdb uninstall` (also requires an administrator command prompt). -Linux -````` - -Ensure Java 11 is installed. On Ubuntu: - -.. code-block:: bash - - sudo apt-get update - sudo apt-get install openjdk-11-jdk-headless - -Once installed, double check that ``java --version`` returns Java 11. Then run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or -:code:`pgdb install` to save data in the default directory. - -Once you have installed PolyglotDB, to start it run :code:`pgdb start`. -Likewise, you can close PolyglotDB by running :code:`pgdb stop`. - -To uninstall, navigate to the PolyglotDB directory and type :code:`pgdb uninstall` - - -Conda Development Environment -============ - -You can also use conda to create an isolated polyglotdb development environment: - -#. Install either Anaconda, miniconda, or miniforge -#. Make sure your conda is up to date (conda update conda) -#. Make sure that you have cloned the polyglotdb repository -#. cd to the source directory - -We’ll now kick off a two-step process: - -#. Create a conda environment to isolate polyglotdb dependencies -#. Build and install polyglotdb - -.. code-block:: bash - - conda env create -f environment.yml - conda activate polyglotdb-dev - -From within the polyglotdb-dev environment, double check that ``java --version`` returns Java 11. Then: - -.. code-block:: bash - - python setup.py install - pgdb install /path/to/where/you/want/data/to/be/stored - -You now have a new conda environment that is isolated from any existing environments or python installations. The pgdb executable will only be accessible from within the polyglotdb-dev environment. -To view your environments: +To view your conda environments: .. code-block:: bash diff --git a/rtd_requirements.txt b/rtd_requirements.txt index 7d202d79..9c91cb47 100755 --- a/rtd_requirements.txt +++ b/rtd_requirements.txt @@ -2,3 +2,4 @@ sphinx numpydoc mock sphinx_rtd_theme +polyglotdb \ No newline at end of file From 3d38e5d05a3401de8d0c25c7e7a78b0e6f38f1ae Mon Sep 17 00:00:00 2001 From: lxy2304 Date: Tue, 30 Jul 2024 00:17:03 -0400 Subject: [PATCH 2/5] Update travis CI script --- .travis.yml | 12 +++++------- continuous-integration/travis/install.sh | 8 ++++---- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/.travis.yml b/.travis.yml index e0758551..cabb9790 100755 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,6 @@ language: python python: - - 3.8 + - 3.12 branches: only: - main @@ -14,7 +14,6 @@ sudo: required addons: apt: packages: - - openjdk-11-jdk - sox - libsndfile1 @@ -34,8 +33,7 @@ install: - pip install -r requirements.txt - which python - conda list - - python bin/pgdb install -q - - python bin/pgdb start + - python polyglotdb/pgdb.py start before_script: - sleep 15 @@ -43,15 +41,15 @@ before_script: # Run test script: - source activate test-environment - - coverage run --source=polyglotdb setup.py test + - coverage run -m pytest after_script: - source activate test-environment - - python bin/pgdb stop + - python polyglotdb/pgdb.py stop # Calculate coverage after_success: - - coveralls + - coveralls cache: pip: true diff --git a/continuous-integration/travis/install.sh b/continuous-integration/travis/install.sh index 361d1b98..975622c0 100755 --- a/continuous-integration/travis/install.sh +++ b/continuous-integration/travis/install.sh @@ -11,11 +11,11 @@ if [ ! -d "$HOME/miniconda/miniconda/envs/test-environment" ]; then conda config --set always_yes yes --set changeps1 no conda update -q conda conda info -a - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION setuptools numpy pytest scipy + conda create -q -n test-environment -c conda-forge openjdk=21 pip conda activate test-environment which python - pip install -q coveralls coverage neo4j-driver textgrid librosa tqdm influxdb conch_sounds - python setup.py install + pip install -q coveralls coverage neo4j textgrid librosa tqdm influxdb conch_sounds pytest + pip install -q -e . else export PATH="$HOME/miniconda/miniconda/bin:$PATH" source "$HOME/miniconda/miniconda/etc/profile.d/conda.sh" @@ -38,7 +38,7 @@ if [ ! -f "$HOME/tools/praat" ]; then grep -Eo 'praat[0-9]+_linux64barren\.tar\.gz' | head -1) # Download. - curl "https://www.fon.hum.uva.nl/praat/praat6151_linux64barren.tar.gz" > praat-latest.tar.gz + curl "https://www.fon.hum.uva.nl/praat/praat6414_linux-intel64-barren.tar.gz" > praat-latest.tar.gz tar -zxvf praat-latest.tar.gz mv praat_barren $HOME/tools/praat else From a7938db8b52bb93b882d313e190f543c6b16148d Mon Sep 17 00:00:00 2001 From: lxy2304 Date: Tue, 30 Jul 2024 00:18:33 -0400 Subject: [PATCH 3/5] Minor change --- docs/source/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index c73c7166..f59ffd5d 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -7,7 +7,7 @@ Changelog Version 1.3.0 ============= -* Upgraded Neo4j compatibility to 5.x +* Upgraded Neo4j compatibility to 5.22 Version 1.2.1 ============= From 607b050c8a663973ef3233422657f8a462228d81 Mon Sep 17 00:00:00 2001 From: Xiaoyi Date: Tue, 30 Jul 2024 14:37:43 -0400 Subject: [PATCH 4/5] Update conf.py --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c6fa745c..917bb62f 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -94,7 +94,7 @@ # General information about the project. project = 'PolyglotDB' -copyright = '2015-2019, Montreal Corpus Tools' +copyright = '2015-2024, Montreal Corpus Tools' author = 'Montreal Corpus Tools' release: str = get_version("polyglotdb") From d45132333b5d81ef5e23a306e26a50b3d4e11576 Mon Sep 17 00:00:00 2001 From: Xiaoyi Date: Tue, 30 Jul 2024 14:44:02 -0400 Subject: [PATCH 5/5] Update changelog.rst --- docs/source/changelog.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index f59ffd5d..4ce1a817 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -7,7 +7,10 @@ Changelog Version 1.3.0 ============= -* Upgraded Neo4j compatibility to 5.22 +* Updated Neo4j Cypher queries to be compatible with Neo4j 5.x syntax. +* Upgraded Neo4j compatibility to version 5.22 and Java compatibility to Java 21. +* Updated the packaging process for smooth installation across platforms. +* Made Conda a required installation dependency. Version 1.2.1 ============= @@ -33,4 +36,4 @@ Version 1.0 * Added ability to enrich tokens from CSV * Added parser for TextGrids generated from the Web-MAUS aligner * Optimized loading of corpora for lower-memory computers -* Optimized queries involving acoustic tracks \ No newline at end of file +* Optimized queries involving acoustic tracks