Merge 2ed7f2e into 30488ca

.gitignore

@@ -10,5 +10,7 @@ docs/_sources/
 docs/.doctrees/
 docs/_templates/
 docs/*.html
-
-
+.idea/
+genologics/__pycache__/
+pyclarity_lims/__pycache__/
+tests/__pycache__/

README.md

@@ -1,85 +1,16 @@
-## Python interface to the BaseSpace Clarity LIMS server via its REST API.
+## Python interface to BaseSpace Clarity LIMS server via its REST API.
 
-[![PyPI version](https://badge.fury.io/py/genologics.svg)](http://badge.fury.io/py/genologics)
+[![PyPI](https://img.shields.io/pypi/v/pyclarity-lims.svg)](https://pypi.python.org/pypi/pyclarity)
+[![PyPI](https://img.shields.io/pypi/pyversions/pyclarity-lims.svg)](https://pypi.python.org/pypi/pyclarity-lims)
+[![travis](https://img.shields.io/travis/EdinburghGenomics/pyclarity-lims/master.svg)](https://travis-ci.org/EdinburghGenomics/pyclarity-lims)
+[![GitHub issues](https://img.shields.io/github/issues/EdinburghGenomics/pyclarity-lims.svg)](https://github.com/EdinburghGenomics/pyclarity-lims/issues)  
+[![Coverage Status](https://coveralls.io/repos/github/EdinburghGenomics/pyclarity-lims/badge.svg)](https://coveralls.io/github/EdinburghGenomics/pyclarity-lims)
 
-A basic module for interacting with the BaseSpace LIMS server via
-its REST API. The goal is to provide simple access to the most common
-entities and their attributes in a reasonably Pythonic fashion.
 
-Supported python versions :
+Pyclarity-lims is a fork of [genologics](https://github.com/SciLifeLab/genologics) that we extended and modified.
+Most of the initial logic still applies and genologics module still exist in pyclarity-lims for backward compatibility.
+However there are a few backward incompatible changes that had to be made.
 
-2.7
-3.4
-3.5
-3.6 (recommended)
+## Documentation
 
-### Design
-
-All instances of Project, Sample, Artifact, etc should be obtained using
-the get_* methods of the Lims class, which keeps an internal cache of
-current instances. The idea is to create one and only one instance in
-a running script for representing an item in the database. If one has
-more than one instance representing the same item, there is a danger that
-one of them gets updated and not the others.
-
-An instance of Project, Sample, Artifact, etc, retrieves lazily (i.e.
-only when required) its XML representation from the database. This
-is parsed and kept as an ElementTree within the instance. All access
-to predefined attributes goes via descriptors which read from or
-modify the ElementTree. This simplifies writing back an updated
-instance to the database.
-
-### Installation
-
-```
-pip install pyclarity-lims
-```
-
-
-### Usage
-
-The URL and credentials should be written in a new file in any
-of those config files (ordered by preference):
-
-```
-$HOME/.genologicsrc, .genologicsrc, genologics.conf, genologics.cfg
-```
-
-or if installed system_wide:
-
-```
-/etc/genologics.conf
-```
-
-```
-[genologics]
-BASEURI=https://yourlims.example.com:8443
-USERNAME=your_username
-PASSWORD=your_password
-[logging]
-MAIN_LOG=/home/glsai/your_main_log_file
-```
-
-### Example scripts
-
-Usage example scripts are provided in the subdirectory 'examples'.
-
-NOTE: The example files rely on specific entities and configurations
-on the server, and use base URI, user name and password, so to work
-for your server, all these must be reviewed and modified.
-
-
-### EPPs
-
-The EPPs in use at Scilifelab can be found in the subdirectory 'scripts' of the repository [scilifelab_epps](https://github.com/SciLifeLab/scilifelab_epps/).
-
-### Pull requests policy
-
-Pull requests are welcome, and will be tested internally before merging. Be aware that this process might take a fair amount of time. 
-
-### Known bugs 
-
-- Artifact state is part of its URL (as a query parameter).
-  It is not entirely clear how to deal with this in the Lims.cache:
-  Currently, an artifact that has the current state may be represented
-  by a URL that includes the state, and another that does not contain it.
+Documentation for pyclarity-lims is available [here](http://pyclarity-lims.readthedocs.io/en/latest/)

docs/Getting_started.rst

@@ -0,0 +1,72 @@
+
+Getting started
+===============
+
+pyclarity-lims is a module that will help you access you `Basespace-clarity <https://www.genologics.com/clarity-lims/>`_ REST API by parsing the xml the API returns and provide python object.
+
+Lims connection
+---------------
+
+To create a lims connection you'll need to create a :py:class:`Lims <pyclarity_lims.lims.Lims>` object.
+.. code::
+
+        from pyclarity_lims.lims import Lims
+
+        l = Lims('https://claritylims.example.com', 'username' , 'Pa55w0rd')
+
+The :py:class:`Lims <pyclarity_lims.lims.Lims>` instance is the main object that will interact with REST API and manage all communications.
+There are two way of accessing information stored in the LIMS:
+
+Searching the Lims
+------------------
+The most common way of accessing data from the LIMS is to first perform searches. For example, retrieving all samples from project1 would be:
+
+.. code::
+
+        samples = l.get_samples(projectname='project1')
+
+This will return the list of :py:class:`Sample <pyclarity_lims.entities.Sample>` objects that belong to project1.
+
+The functions from pyclarity_lims closely match the API search function from Basespace-clarity REST API. For example
+:py:func:`get_samples <pyclarity_lims.lims.Lims.get_samples>` has similar parameters as the
+`samples end point <https://www.genologics.com/files/permanent/API/latest/rest.version.samples.html>`_ from Basespace-clarity
+
+Retrieving object with their id
+-------------------------------
+In some case you will know the id or uri of the instance you want to retrieve. In this case you can create the object directly.
+
+Note that you will still need the :py:class:`Lims <pyclarity_lims.lims.Lims>` instance as an argument.
+
+For Example:
+
+.. code::
+
+        from pyclarity_lims.entities import Sample
+        sample = Sample(l, id='sample_luid')
+        print(sample.name)
+
+Lazy loading and caching
+------------------------
+All entities such as :py:class:`Sample <pyclarity_lims.entities.Sample>`,
+:py:class:`Artifact <pyclarity_lims.entities.Artifact>` or
+:py:class:`Step <pyclarity_lims.entities.Step>` are loaded lazily which mean that no query will be sent to the REST API
+until an attribute of method of the object is accessed.
+In the code above
+
+.. code::
+
+        from pyclarity_lims.entities import Sample
+        sample = Sample(l, id='sample_luid')
+        # the Sample object has been created but no query have been sent yet
+        print(sample.name)
+        # accessing the name of the sample triggers the query
+
+To avoid sending to many queries all Entities that have been retrieved are also cached which means that once the Entity is retrieved it won't be queried unless forced.
+This make pyclarity_lims more efficient but very well suited for long running process during which the state of the LIMS is likely to change.
+You can bypass the cache as shown in :ref:`up-to-date-program-status`.
+
+Looking beyond
+--------------
+You can look at some :doc:`PracticalExamples`
+There are many other searches method available in the :py:class:`Lims <pyclarity_lims.lims.Lims>` and
+you can also look at all the classes defined in :doc:`entities`

docs/Installation.rst

@@ -0,0 +1,8 @@
+
+Installation
+=============
+
+.. code:: bash
+
+   pip install pyclarity-lims
+

docs/Makefile

@@ -1,177 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = pyclarity-lims
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Genologics.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Genologics.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/Genologics"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Genologics"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+.PHONY: help Makefile
 
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)