From 39a422ce6dfc09d1267d737907eb5e3c17b74de9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=C5=9Aliwi=C5=84ski?= Date: Fri, 7 May 2021 11:44:11 +0200 Subject: [PATCH] Move relevant docs to README, mention Windows Support - closes #453 --- CHANGES.rst | 1 + README.rst | 207 ++++++++++++++++++++-- docs/Makefile | 153 ---------------- docs/make.bat | 190 -------------------- docs/source/api.rst | 8 - docs/source/api/exceptions.rst | 5 - docs/source/api/executors.rst | 20 --- docs/source/authors.rst | 3 - docs/source/basic.rst | 195 --------------------- docs/source/changelog.rst | 3 - docs/source/conf.py | 307 --------------------------------- docs/source/contributing.rst | 3 - docs/source/index.rst | 20 --- 13 files changed, 197 insertions(+), 918 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/make.bat delete mode 100644 docs/source/api.rst delete mode 100644 docs/source/api/exceptions.rst delete mode 100644 docs/source/api/executors.rst delete mode 100644 docs/source/authors.rst delete mode 100644 docs/source/basic.rst delete mode 100644 docs/source/changelog.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/contributing.rst delete mode 100644 docs/source/index.rst diff --git a/CHANGES.rst b/CHANGES.rst index 0d123e76..007ac64a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -9,6 +9,7 @@ Misc - Moved CI to Github Actions - Blackified codebase +- Compacted Documentation into readme (was pretty small anyway) 2.3.0 ---------- diff --git a/README.rst b/README.rst index eab9e324..9edb714b 100644 --- a/README.rst +++ b/README.rst @@ -43,7 +43,7 @@ Package status :alt: Coverage Status -About +Usage ----- In a project that relies on multiple processes there might be a need to guard code @@ -67,6 +67,134 @@ Library provides seven executors to fit different cases: * **HTTPExecutor** - waits for a successful HEAD request (and TCP before). * **PidExecutor** - waits for a specified .pid file to exist. +SimpleExecutor +++++++++++++++ + +The simplest executor implementation. +It simply starts the process passed to constructor, and reports it as running. + +.. code-block:: python + + from mirakuru import SimpleExecutor + + process = SimpleExecutor('my_special_process') + process.start() + + # Here you can do your stuff, e.g. communicate with the started process + + process.stop() + +OutputExecutor +++++++++++++++ + +OutputExecutor is the executor that starts the process, +but does not report it as started, unless it receives specified marker/banner in +process output. + +.. code-block:: python + + from mirakuru import OutputExecutor + + process = OutputExecutor('my_special_process', banner='processed!') + process.start() + + # Here you can do your stuff, e.g. communicate with the started process + + process.stop() + +What happens during start here, is that the executor constantly checks output +produced by started process, and looks for the banner part occurring within the +output. +Once the output is identified, as in example `processed!` is found in output. +It is considered as started, and executor releases your script from wait to work. + + +TCPExecutor ++++++++++++ + +Is the executor that should be used to start +processes that are using TCP connection. This executor tries to connect with +the process on given host:port to see if it started accepting connections. Once it +does, it reports the process as started and a code returns to normal execution. + +.. code-block:: python + + from mirakuru import TCPExecutor + + process = TCPExecutor('my_special_process', host='localhost', port=1234) + process.start() + + # Here you can do your stuff, e.g. communicate with the started process + + process.stop() + +HTTPExecutor +++++++++++++ + +Is executor that will be used to start web applications for example. +To start it, you apart from command, you need to pass a URL. +This URL will be used to make a (by default) HEAD request. Once successful, +the executor will be considered started, and a code will return to normal execution. + +.. code-block:: python + + from mirakuru import HTTPExecutor + + process = HTTPExecutor('my_special_process', url='http://localhost:6543/status') + process.start() + + # Here you can do your stuff, e.g. communicate with the started process + + process.stop() + +This executor, however, apart from HEAD request, also inherits TCPExecutor, +so it'll try to connect to process over TCP first, to determine, +if it can try to make a HEAD request already. + +By default HTTPExecutor waits until its subprocess responds with 2XX HTTP status code. +If you consider other codes as valid you need to specify them in 'status' argument. + +.. code-block:: python + + from mirakuru import HTTPExecutor + + process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)') + process.start() + +The "status" argument can be a single code integer like 200, 404, 500 or a regular expression string - +'^(2|4)00$', '2\d\d', '\d{3}', etc. + +There's also a possibility to change the request method used to perform request to the server. +By default it's HEAD, but GET, POST or other are also possible. + +.. code-block:: python + + from mirakuru import HTTPExecutor + + process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)', method='GET') + process.start() + + +PidExecutor ++++++++++++ + +Is an executor that starts the given +process, and then waits for a given file to be found before it gives back control. +An example use for this class is writing integration tests for processes that +notify their running by creating a .pid file. + +.. code-block:: python + + from mirakuru import PidExecutor + + process = PidExecutor('my_special_process', filename='/var/msp/my_special_process.pid') + process.start() + + # Here you can do your stuff, e.g. communicate with the started process + + process.stop() + + .. code-block:: python from mirakuru import HTTPExecutor @@ -99,18 +227,61 @@ A command by which executor spawns a process can be defined by either string or host='localhost', port=1025 ) -Authors -------- +Use as a Context manager +------------------------ + +Starting +++++++++ + +Mirakuru executors can also work as a context managers. + +.. code-block:: python + + from mirakuru import HTTPExecutor + + with HTTPExecutor('my_special_process', url='http://localhost:6543/status') as process: + + # Here you can do your stuff, e.g. communicate with the started process + assert process.running() is True -The project was firstly developed by `Mateusz Lenik `_ -as the `summon_process `_. -Later forked, renamed into **mirakuru** and tended to by The A Room @ `Clearcode `_ -and `the other authors `_. + assert process.running() is False -License -------- +Defined process starts upon entering context, and exit upon exiting it. -``mirakuru`` is licensed under LGPL license, version 3. +Stopping +++++++++ + +Mirakuru also allows to stop process for given context. +To do this, simply use built-in stopped context manager. + +.. code-block:: python + + from mirakuru import HTTPExecutor + + process = HTTPExecutor('my_special_process', url='http://localhost:6543/status').start() + + # Here you can do your stuff, e.g. communicate with the started process + + with process.stopped(): + + # Here you will not be able to communicate with the process as it is killed here + assert process.running() is False + + assert process.running() is True + +Defined process stops upon entering context, and starts upon exiting it. + + +Methods chaining +++++++++++++++++ + +Mirakuru encourages methods chaining so you can inline some operations, e.g.: + +.. code-block:: python + + from mirakuru import SimpleExecutor + + command_stdout = SimpleExecutor('my_special_process').start().stop().output Contributing and reporting bugs ------------------------------- @@ -119,4 +290,18 @@ Source code is available at: `ClearcodeHQ/mirakuru `_. Projects `PyPI page `_. -When contributing, don't forget to add your name to the AUTHORS.rst file. +Windows support +--------------- + +Frankly, there's none, Python's support differs a bit in required places +and the team has no experience in developing for Windows. +However we'd welcome contributions that will allow the windows support. + +See: + +* `#392 `_ +* `#336 `_ + +Also, With the introduction of `WSL `_ +the need for raw Windows support might not be that urgant... If you've got any thoughts or are willing to contribute, +please start with the issues listed above. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index fe20658a..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html html_venv dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where 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 " 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 " 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/Subscribepyramidplugin.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Subscribepyramidplugin.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/Subscribepyramidplugin" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Subscribepyramidplugin" - @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." - -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." diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 0c5f8f62..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ 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. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Subscribepyramidplugin.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Subscribepyramidplugin.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index e9ea4d5f..00000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,8 +0,0 @@ -Api -=== - -.. toctree:: - :maxdepth: 2 - - api/executors - api/exceptions diff --git a/docs/source/api/exceptions.rst b/docs/source/api/exceptions.rst deleted file mode 100644 index 36506870..00000000 --- a/docs/source/api/exceptions.rst +++ /dev/null @@ -1,5 +0,0 @@ -Exceptions -========== - -.. automodule:: mirakuru.exceptions - :members: diff --git a/docs/source/api/executors.rst b/docs/source/api/executors.rst deleted file mode 100644 index 38ef03fc..00000000 --- a/docs/source/api/executors.rst +++ /dev/null @@ -1,20 +0,0 @@ -Basic executors -=============== - -.. automodule:: mirakuru.base - :private-members: - -.. automodule:: mirakuru.output - :private-members: - -.. automodule:: mirakuru.unixsocket - :private-members: - -.. automodule:: mirakuru.tcp - :private-members: - -.. automodule:: mirakuru.http - :private-members: - -.. automodule:: mirakuru.pid - :private-members: diff --git a/docs/source/authors.rst b/docs/source/authors.rst deleted file mode 100644 index 0181789f..00000000 --- a/docs/source/authors.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _authors: - -.. include:: ../../AUTHORS.rst diff --git a/docs/source/basic.rst b/docs/source/basic.rst deleted file mode 100644 index e06dda64..00000000 --- a/docs/source/basic.rst +++ /dev/null @@ -1,195 +0,0 @@ -Basic executors -=============== - -Mirakuru :class:`~mirakuru.base.Executor` is something that you will use when you -need to make some code dependant from other process being run, and in certain state, -and you wouldn't want this process to be running all the time. - -Tests would be best example here or a script that sets up processes and databases -for dev environment with one simple run. - - -SimpleExecutor --------------- - -:class:`mirakuru.base.SimpleExecutor` is the simplest executor implementation. -It simply starts the process passed to constructor, and reports it as running. - -.. code-block:: python - - from mirakuru import SimpleExecutor - - process = SimpleExecutor('my_special_process') - process.start() - - # Here you can do your stuff, e.g. communicate with the started process - - process.stop() - -OutputExecutor --------------- - -:class:`mirakuru.output.OutputExecutor` is the executor that starts the process, -but does not report it as started, unless it receives specified marker/banner in -process output. - -.. code-block:: python - - from mirakuru import OutputExecutor - - process = OutputExecutor('my_special_process', banner='processed!') - process.start() - - # Here you can do your stuff, e.g. communicate with the started process - - process.stop() - -What happens during start here, is that the executor constantly checks output -produced by started process, and looks for the banner part occurring within the -output. -Once the output is identified, as in example `processed!` is found in output. -It is considered as started, and executor releases your script from wait to work. - - -TCPExecutor ------------ - -:class:`mirakuru.tcp.TCPExecutor` is the executor that should be used to start -processes that are using TCP connection. This executor tries to connect with -the process on given host:port to see if it started accepting connections. Once it -does, it reports the process as started and a code returns to normal execution. - -.. code-block:: python - - from mirakuru import TCPExecutor - - process = TCPExecutor('my_special_process', host='localhost', port=1234) - process.start() - - # Here you can do your stuff, e.g. communicate with the started process - - process.stop() - - -HTTPExecutor ------------- - -:class:`mirakuru.http.HTTPExecutor` is executor that will be used to start -web applications for example. To start it, you apart from command, you need to pass a URL. -This URL will be used to make a (by default) HEAD request. Once successful, -the executor will be considered started, and a code will return to normal execution. - -.. code-block:: python - - from mirakuru import HTTPExecutor - - process = HTTPExecutor('my_special_process', url='http://localhost:6543/status') - process.start() - - # Here you can do your stuff, e.g. communicate with the started process - - process.stop() - -This executor, however, apart from HEAD request, also inherits TCPExecutor, -so it'll try to connect to process over TCP first, to determine, -if it can try to make a HEAD request already. - -By default HTTPExecutor waits until its subprocess responds with 2XX HTTP status code. -If you consider other codes as valid you need to specify them in 'status' argument. - -.. code-block:: python - - from mirakuru import HTTPExecutor - - process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)') - process.start() - -The "status" argument can be a single code integer like 200, 404, 500 or a regular expression string - -'^(2|4)00$', '2\d\d', '\d{3}', etc. - -There's also a possibility to change the request method used to perform request to the server. -By default it's HEAD, but GET, POST or other are also possible. - -.. code-block:: python - - from mirakuru import HTTPExecutor - - process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)', method='GET') - process.start() - - -PidExecutor ------------ - -:class:`mirakuru.pid.PidExecutor` is an executor that starts the given -process, and then waits for a given file to be found before it gives back control. -An example use for this class is writing integration tests for processes that -notify their running by creating a .pid file. - -.. code-block:: python - - from mirakuru import PidExecutor - - process = PidExecutor('my_special_process', filename='/var/msp/my_special_process.pid') - process.start() - - # Here you can do your stuff, e.g. communicate with the started process - - process.stop() - - -As a Context manager --------------------- - -Starting -++++++++ - -Mirakuru executors can also work as a context managers. - -.. code-block:: python - - from mirakuru import HTTPExecutor - - with HTTPExecutor('my_special_process', url='http://localhost:6543/status') as process: - - # Here you can do your stuff, e.g. communicate with the started process - assert process.running() is True - - assert process.running() is False - -Defined process starts upon entering context, and exit upon exiting it. - -Stopping -++++++++ - -Mirakuru also allows to stop process for given context. -To do this, simply use built-in stopped context manager. - -.. code-block:: python - - from mirakuru import HTTPExecutor - - process = HTTPExecutor('my_special_process', url='http://localhost:6543/status').start() - - # Here you can do your stuff, e.g. communicate with the started process - - with process.stopped(): - - # Here you will not be able to communicate with the process as it is killed here - assert process.running() is False - - assert process.running() is True - -Defined process stops upon entering context, and starts upon exiting it. - - -Methods chaining ----------------- - -Mirakuru encourages methods chaining so you can inline some operations, e.g.: - -.. code-block:: python - - from mirakuru import SimpleExecutor - - command_stdout = SimpleExecutor('my_special_process').start().stop().output diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst deleted file mode 100644 index cca37260..00000000 --- a/docs/source/changelog.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _changelog: - -.. include:: ../../CHANGES.rst diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 443ee0cc..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,307 +0,0 @@ -# Copyright (C) 2014 by Clearcode -# and associates (see AUTHORS). - -# This file is part of mirakuru. - -# mirakuru is free software: you can redistribute it and/or modify -# it under the terms of the GNU Lesser General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# mirakuru is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Lesser General Public License for more details. - -# You should have received a copy of the GNU Lesser General Public License -# along with mirakuru. If not, see . - -import sys -import os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.viewcode", - "sphinx.ext.intersphinx", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = ".rst" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "mirakuru" -basename = "".join(project.split(".")) -author = "The A Room @ Clearcode" -copyright = "2014, " + author - -# 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. - -from mirakuru import __version__ - -# The full version, including alpha/beta/rc tags. -release = __version__ - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = "default" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = basename + "doc" - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ("index", basename + ".tex", project + " Documentation", author, "manual"), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [("index", basename, project + " Documentation", [author], 1)] - -# If true, show URL addresses after external links. -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - "index", - basename, - project + " Documentation", - author, - basename, - "One line description of project.", - "Miscellaneous", - ), -] - -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = "2014, " + author - -# The language of the text. It defaults to the language option -# or en if the language is not set. -# epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -# epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# epub_identifier = '' - -# A unique identification for the text. -# epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -# epub_cover = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -# epub_post_files = [] - -# A list of files that should not be packed into the epub file. -# epub_exclude_files = [] - -# The depth of the table of contents in toc.ncx. -# epub_tocdepth = 3 - -# Allow duplicate toc entries. -# epub_tocdup = True - -# Autodoc configuration: - -autoclass_content = "both" -autodoc_default_flags = ["members", "show-inheritance"] - -# Intersphinx configuration -intersphinx_mapping = {"python": ("http://docs.python.org/", None)} diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst deleted file mode 100644 index 2b6578f6..00000000 --- a/docs/source/contributing.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _contributing: - -.. include:: ../../CONTRIBUTING.rst diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index a1a7197f..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. include:: ../../README.rst - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - basic - api - contributing - changelog - - -License -------- - -Copyright (c) 2014 by Clearcode, mirakuru authors and contributors. See :ref:`authors` - -This module is part of mirakuru and is released under the LGPL license, version 3.