# HG changeset patch # User Thierry Florac # Date 1515938481 -3600 # Node ID 985534bc6ab9e84ae91bd353c7dd7224b0b8f0a6 # Parent 53dc81f933edfd6c9f43826fcd1e2fa4d57e845c Version 0.1.10 diff -r 53dc81f933ed -r 985534bc6ab9 buildout.cfg --- a/buildout.cfg Thu Jan 11 16:57:23 2018 +0100 +++ b/buildout.cfg Sun Jan 14 15:01:21 2018 +0100 @@ -35,7 +35,6 @@ package i18n pyflakes - sphinx test [package] @@ -92,19 +91,9 @@ on_install = true cmds = ${buildout:develop}/bin/${pyflakes:scripts} -[sphinx] -recipe = collective.recipe.sphinxbuilder -eggs = - ${package:eggs} - pyams_form - pyams_zmi -source = ${buildout:directory}/docs/source -build = ${buildout:directory}/docs/build -interpreter = ${buildout:directory}/bin/py - [test] recipe = zc.recipe.testrunner eggs = pyams_utils [test] [versions] -pyams_utils = 0.1.9 +pyams_utils = 0.1.10 diff -r 53dc81f933ed -r 985534bc6ab9 docs/HISTORY.txt --- a/docs/HISTORY.txt Thu Jan 11 16:57:23 2018 +0100 +++ b/docs/HISTORY.txt Sun Jan 14 15:01:21 2018 +0100 @@ -1,6 +1,12 @@ Changelog ========= +0.1.10 +------ + - added ZODB connection class and vocabulary based on Pyramid's settings + - updated DocFieldProperty to correctly handle attributes documentation + - small updates in registry management functions + 0.1.9 ----- - added "NullAdapter" class to be able to remove a default adapter for a given context diff -r 53dc81f933ed -r 985534bc6ab9 docs/Makefile --- a/docs/Makefile Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,225 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = ../bin/py ../bin/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 -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 " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " epub3 to make an epub3" - @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)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to check syntax errors of document sources" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -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." - -.PHONY: qthelp -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/PyAMS_utils.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyAMS_utils.qhc" - -.PHONY: applehelp -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/PyAMS_utils" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyAMS_utils" - @echo "# devhelp" - -.PHONY: epub -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: epub3 -epub3: - $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 - @echo - @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." - -.PHONY: latex -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)." - -.PHONY: latexpdf -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." - -.PHONY: latexpdfja -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." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -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)." - -.PHONY: info -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." - -.PHONY: gettext -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -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." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -.PHONY: dummy -dummy: - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy - @echo - @echo "Build finished. Dummy builder generates no files." diff -r 53dc81f933ed -r 985534bc6ab9 docs/make.bat --- a/docs/make.bat Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,281 +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. epub3 to make an epub3 - 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. 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 - echo. coverage to run coverage check of the documentation if enabled - echo. dummy to check syntax errors of document sources - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 1>NUL 2>NUL -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -:sphinx_ok - - -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\PyAMS_utils.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyAMS_utils.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" == "epub3" ( - %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. - 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" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF 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 -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -if "%1" == "dummy" ( - %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. Dummy builder generates no files. - goto end -) - -:end diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/_static/zeo-add-form.png Binary file docs/source/_static/zeo-add-form.png has changed diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/_static/zeo-add-menu.png Binary file docs/source/_static/zeo-add-menu.png has changed diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/conf.py --- a/docs/source/conf.py Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,341 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# PyAMS_utils documentation build configuration file, created by -# sphinx-quickstart on Tue Nov 15 16:18:42 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# 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. -# -# import os -# import sys -# 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', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -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 = 'PyAMS_utils' -copyright = '2017, Thierry Florac ' -author = 'Thierry Florac ' - -# 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 = '0.1' -# The full version, including alpha/beta/rc tags. -release = '0.1.5' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -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. -# This patterns also effect to html_static_path and html_extra_path -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 = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- 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 = 'pyramid' - -# 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. -# " v documentation" by default. -# -# html_title = 'PyAMS_utils v0.1.4' - -# 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 (relative to this directory) to use as a 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# 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 - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'PyAMS_utilsdoc' - -# -- 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': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'PyAMS_utils.tex', 'PyAMS\\_utils Documentation', - 'Thierry Florac \\textless{}tflorac@ulthar.net\\textgreater{}', '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 = [] - -# It false, will not define \strong, \code, itleref, \crossref ... but only -# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added -# packages. -# -# latex_keep_old_macro_names = True - -# 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 = [ - (master_doc, 'pyams_utils', 'PyAMS_utils 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 = [ - (master_doc, 'PyAMS_utils', 'PyAMS_utils Documentation', - author, 'PyAMS_utils', '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' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/index.rst --- a/docs/source/index.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,51 +0,0 @@ -.. PyAMS_utils documentation master file, created by - sphinx-quickstart on Tue Nov 15 16:18:42 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -.. _index: - - -**WARNING**: this is a "work-in-progress" documentation. All elements described here are not publicly available yet!!! - - -Welcome to PyAMS_utils's documentation! -======================================= - -At first, PyAMS was "Pyramid Application Management Skin". Actually, it's not only a simple skin but a whole "Suite" of -applications and content management tools. - -PyAMS_utils is a multipurpose utilities package, providing tools including: - - - custom interfaces - - - custom ZCA registry annotations - - - local registry support - - - network protocols utilities (for HTTP and XML-RPC) - - - custom utilities - - - a command line script to handle database upgrade process - - -.. toctree:: - :maxdepth: 2 - - install - zeo - zca - site - traverser - tales - utilities - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modules` -* :ref:`modindex` -* :ref:`search` diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/install.rst --- a/docs/source/install.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,271 +0,0 @@ -.. _install: - -Installing PyAMS -================ - -PyAMS default installation is based on `Buildout `_ utility. It's not mandatory to use a -virtual environment, but it allows you to have a better control over your Python resources. - -Current PyAMS version is based and validated for Python 3.5; your Python environment must also include a C -compiler as well as development headers for Python, *libjpeg*, *libpng*, *libfreetype*, *libxml2*, *libxslt* and -eventually *libldap* or *libzmq*. - -PyAMS default components configuration also pre-suppose that the following external tools are available: - -- a *Memcached* or *Redis* server, to store sessions and cache (can be changed through Beaker configuration) - -Optional tools also include: - -- an *LDAP* server for authentication - -- an *ElasticSearch* server for full text indexing (see *PyAMS_content_es* package) - -- a *WebSockets* server using AsyncIO. This is used to manage notifications (see *PyAMS_notify* and *PyAMS_notify_ws* - packages). An *out of the box* environment can be built using *pyams_notify* scaffold. - - -PyAMS also needs that you use a ZEO server, as several background processes needing a concurrent access to ZODB are -started by PyAMS main process. See :ref:`zeo` to know how to create a ZEO server with the help of PyAMS tools. - - -Creating initial buildout -------------------------- - -PyAMS provides a new Pyramid scaffold, called *pyams*, generated via a *cookiecutter* template. - -A simple option to install PyAMS is to create a buildout environment including *Pyramid* and all *PyAMS* packages: - -.. code-block:: bash - - # mkdir /var/local/ - # pip3 install virtualenv - # virtualenv --python=python3.5 env - # cd env - # . bin/activate - (env) # pip3.5 install cookiecutter - (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/pyams - -*CookieCutter* will ask you for a small set of input variables that you can change or not: - -- **pyams_release**: version of PyAMS configuration file to use. "latest" (default value) will point to last release; - you can also choose to point to a given release ("0.1.4" for example) - -- **project_name**: current environment name in "human form" - -- **project_slug**: "technical" package name, based on project name - -- **virtual_hostname**: Apache virtual-host name - -- **webapp_name**: web application package name ("webapp" as default) - -- **webapp_port**: TCP/IP port to use when running application outside Apache ("6543" as default) - -- **eggs_directory**: relative or absolute path to directory containing downloaded eggs; this directory can be - shared with other projects ("eggs" as default) - -- **logs_directory**: absolute path to directory containing Apache's log files - -- **run_user**: user name under which Apache process will run ("www-data" as default) - -- **run_group**: group name under which Apache process will run ("www-data" as default) - -- **beaker_backend**: name of Beaker backend to use to store sessions and cache data ("redis" as default) - -- **beaker_server**: IP address and port of Beaker backend server ("127.0.0.1:6379" as default) - -- **zeo_server**: IP address and port of ZEO server ("127.0.0.1:8100" as default); WARNING: ZEO server installation - is not part of application installation; another "zeo_server" cookiecutter receipe is available for that. - -- **zeo_storage**: name of ZEO storage to use - -- **zeo_username**: ZEO user name - -- **zeo_password**: ZEO password - -- **zeo_realm**: ZEO authentication realm - -- **zeo_blobs_dir**: local directory to use to store cache of ZODB blobs; cache size is limited to 1GB as default - -- **use_postgresql**: specify if PostgreSQL access is required; if so, please check that PostgreSQL development files - are available to compile PsycoPG2 extension - -- **use_oracle**: specify if Oracle access is available; if so, please check that Oracle development files are - available to compile cx_Oracle extension, and that ORACLE_HOME environment variable is correctly defined - -- **use_ldap**: specify if LDAP access will be required for authentication - -- **use_elasticsearch**: specify if an ElasticSearch server will be used for indexation - -- **elasticsearch_server**: URL used to access Elasticsearch server ("http://127.0.0.1:9200" as default); this URL can - include login and password ("http://login:password@127.0.0.1:9200"), if required... - -- **elasticsearch_index**: name of Eslasticsearch index to use ("pyams" as default) - -- **create_elasticsearch_index**: specify if Elasticsearch index should be created after installation is complete - -- **define_elasticsearch_mappings** : specify if Elasticsearch mappings should be defined after installation is complete - -- **smtp_server**: DNS name of SMTP server ("localhost" as default) - -- **smtp_server_name**: "human" name given to SMTP server ("pyams" as default) - -- **pyams_scheduler**: TCP/IP address and port to use to access PyAMS tasks scheduler process ("127.0.0.1:5555" as - default) - -- **pyams_medias_converter**: TCP/IP address and port to use to access PyAMS medias converter process ("127.0.0.1:5556" - as default) - -- **pyams_es_indexer**: TCP/IP address and port to use to access PyAMS Elasticsearch indexer process ("127.0.0.1:5557" - as default) - -- **use_notifications**: specify if PyAMS notifications services are to be used - -- **pyams_ws_notify**: TCP/IP address and port of PyAMS websockets server managing notifications service - ("127.0.0.1:8081" as default) - -- **lexicon_languages**: NLTK lexicon languages to use ("en:english fr:french" as default) - -- **extension_package**: name of a PyAMS extension package to include in environment configuration - -- **need_pyams_gis**: specify if PyAMS GIS features are to be used by given extension package; if so, please check - that *libgdal* development files are available and on Debian, you have to specify environment variables for - C_INCLUDE_PATH and CPLUS_INCLUDE_PATH pointing to */usr/include/gdal* directory. WARNING: you have to check also - that your *libgdal* release is matching "GDAL" release given in PyAMS configuration file (actually 2.1.0). - - -You can then check, and eventually update, the proposed Buildout configuration file *buildout.cfg*, to add or remove -packages or update settings to your needs. Then finalize Bootstrap initialization: - -.. code-block:: bash - - (env) # python3.5 bootstrap.py - (env) # ./bin/buildout - -This last operation can be quite long, as many packages have to downloaded, compiled and installed in the virtual -environment. If you encounter any compile error, just install the required dependencies and restart the buildout. - - -Environment settings --------------------- - -The project generated from *pyams* scaffold is based on default Pyramid's *zodb* scaffold, but it adds: - -- a custom application factory, in the *webapp* directory (see :ref:`site`) - -- a set of directories to store runtime data, in the *var* directory; each directory contains a *README.txt* file - which should be self-explanatory to indicate what this directory should contain, including a ZEO cache - -- a set of configuration files, in the *etc* directory; here are standard *development.ini* and *production.ini* - configuration files, a ZODB configuration files (*zodb-zeo.conf*) for a ZEO client storage and two Apache - configurations (for Apache 2.2 and 2.4) using *mod_wsgi*. - -Once the project have been created from the scaffold, you are free to update all the configuration files. - -If you need to add packages to the environment, you have to add them to the *buildout.cfg* file **AND** to the INI -file (in the *pyramid.includes* section) before running the *buildout* another time; don't forget to add the -requested version at the end of *buildout.cfg* file, as Buildout is not configured by default to automatically -download the last release of a given unknown package. - -*development.ini* and *production.ini* files contain many commented directives related to PyAMS components. Read and -update them carefully before initializing your application database! - - -Initializing the database -------------------------- - -When you have downloaded and installed all required packages, you have to initialize the database so that all -required components are available. - -From a shell, just type: - -.. code-block:: bash - - (env) # ./bin/pyams_upgrade etc/development.ini - -This process requires that every package is correctly included into *pyramid.includes* directive from selected -configuration file. - - -Starting the application ------------------------- - -When database upgrade process has ended, you can start the web application process with the standard Pyramid's -*pserve* command line tool: - -.. code-block:: bash - - (env) # ./bin/pserve etc/development.ini - -In standard debug mode, all registered components are displayed in the console, until the final line (here using ZEO): - -.. code-block:: bash - - 2017-06-19 17:21:40,495 INFO [ZEO.ClientStorage][MainThread] [('localhost', 8100)] ClientStorage (pid=23253) created RW/normal for storage: 'pyams' - 2017-06-19 17:21:40,497 DEBUG [ZODB.blob][MainThread] (23253) Blob directory `var/db/blobs` has layout marker set. Selected `bushy` layout. - 2017-06-19 17:21:40,497 WARNI [ZODB.blob][MainThread] (23253) Blob dir var/db/blobs/ has insecure mode setting - 2017-06-19 17:21:40,498 INFO [ZEO.cache][MainThread] created temporary cache file 4 - 2017-06-19 17:21:40,517 BLATH [ZEO.zrpc][MainThread] (23253) CM.connect(): starting ConnectThread - 2017-06-19 17:21:40,518 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: attempting to connect on 1 sockets - 2017-06-19 17:21:40,524 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: attempt to connect to ('127.0.0.1', 8100) - 2017-06-19 17:21:40,525 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned EINPROGRESS - 2017-06-19 17:21:40,525 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: select() 0, 1, 0 - 2017-06-19 17:21:40,526 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned 0 - 2017-06-19 17:21:40,526 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Testing connection - 2017-06-19 17:21:40,527 INFO [ZEO.zrpc.Connection(b'C')][[('localhost', 8100)] zeo client networking thread] (127.0.0.1:8100) received handshake b'Z4' - 2017-06-19 17:21:40,628 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Server authentication protocol None - 2017-06-19 17:21:40,629 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Connected to storage: ('localhost', 8100) - 2017-06-19 17:21:40,630 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] No verification necessary -- empty cache - 2017-06-19 17:21:40,631 DEBUG [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] pickled inval None b'\x03\xc0\n*g\xcf\xcd\xbb' - 2017-06-19 17:21:40,633 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1) - ... - 2017-06-19 17:22:39,342 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:39,342 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:39,343 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:39,344 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:39,344 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:39,345 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - ... - 2017-06-19 17:22:40,221 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (, , ) providing - 2017-06-19 17:22:40,222 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (,) providing - 2017-06-19 17:22:40,233 DEBUG [PyAMS (utils)][MainThread] Registering adapter for (,) providing - 2017-06-19 17:22:40,244 DEBUG [config][MainThread] include onf_website/configure.zcml - 2017-06-19 17:22:40,245 DEBUG [config][MainThread] include eggs/pyramid_zcml-1.1.0-py3.5.egg/pyramid_zcml/configure.zcml - 2017-06-19 17:22:40,246 DEBUG [config][MainThread] include eggs/pyramid_zcml-1.1.0-py3.5.egg/pyramid_zcml/meta.zcml - 2017-06-19 17:22:40,252 DEBUG [config][MainThread] include eggs/zope.i18n-4.1.0-py3.5.egg/zope/i18n/meta.zcml - 2017-06-19 17:22:40,253 DEBUG [zope.i18n][MainThread] register directory onf_website/src/onf_website/locales - 2017-06-19 17:22:40,258 DEBUG [config][MainThread] include webapp/webapp/configure.zcml - ... - 2017-06-19 17:22:41,288 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1) - 2017-06-19 17:22:41,288 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: exiting thread: Connect([(, ('localhost', 8100))]) - 2017-06-19 17:22:41,303 DEBUG [PyAMS (scheduler][MainThread] Adding scheduler job for task 'Compactage ZEO' - 2017-06-19 17:22:41,304 INFO [apscheduler.scheduler][MainThread] Adding job tentatively -- it will be properly scheduled when the scheduler starts - 2017-06-19 17:22:41,305 DEBUG [PyAMS (scheduler][MainThread] Starting tasks scheduler ... - 2017-06-19 17:22:41,313 INFO [apscheduler.scheduler][MainThread] Added job "Compactage ZEO" to job store "default" - 2017-06-19 17:22:41,314 INFO [apscheduler.scheduler][MainThread] Scheduler started - 2017-06-19 17:22:41,314 DEBUG [apscheduler.scheduler][APScheduler] Looking for jobs to run - 2017-06-19 17:22:41,315 DEBUG [apscheduler.scheduler][APScheduler] Next wakeup is due at 2017-06-20 03:00:00+02:00 (in 34638.684629 seconds) - 2017-06-19 17:22:41,326 INFO [ZEO.ClientStorage][MainThread] [('localhost', 8100)] ClientStorage (pid=23253) created RW/normal for storage: 'pyams' - 2017-06-19 17:22:41,327 DEBUG [ZODB.blob][MainThread] (23253) Blob directory `var/db/blobs` has layout marker set. Selected `bushy` layout. - 2017-06-19 17:22:41,328 WARNI [ZODB.blob][MainThread] (23253) Blob dir var/db/blobs/ has insecure mode setting - 2017-06-19 17:22:41,329 INFO [ZEO.cache][MainThread] created temporary cache file 15 - 2017-06-19 17:22:41,382 BLATH [ZEO.zrpc][MainThread] (23253) CM.connect(): starting ConnectThread - 2017-06-19 17:22:41,383 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: attempting to connect on 1 sockets - 2017-06-19 17:22:41,383 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: attempt to connect to ('127.0.0.1', 8100) - 2017-06-19 17:22:41,384 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned EINPROGRESS - 2017-06-19 17:22:41,385 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: select() 0, 1, 0 - 2017-06-19 17:22:41,385 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CW: connect_ex(('127.0.0.1', 8100)) returned 0 - 2017-06-19 17:22:41,386 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Testing connection - 2017-06-19 17:22:41,386 INFO [ZEO.zrpc.Connection(b'C')][[('localhost', 8100)] zeo client networking thread] (127.0.0.1:8100) received handshake b'Z4' - 2017-06-19 17:22:41,487 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Server authentication protocol None - 2017-06-19 17:22:41,488 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] Connected to storage: ('localhost', 8100) - 2017-06-19 17:22:41,489 INFO [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] [('localhost', 8100)] No verification necessary -- empty cache - 2017-06-19 17:22:41,490 DEBUG [ZEO.ClientStorage][Connect([(, ('localhost', 8100))])] pickled inval None b'\x03\xc0\n*g\xcf\xcd\xbb' - 2017-06-19 17:22:41,492 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CM.connect_done(preferred=1) - 2017-06-19 17:22:41,493 BLATH [ZEO.zrpc][Connect([(, ('localhost', 8100))])] (23253) CT: exiting thread: Connect([(, ('localhost', 8100))]) - 2017-06-19 17:22:41,498 DEBUG [PyAMS (media)][MainThread] Starting medias conversion process ... - 2017-06-19 17:22:41,503 DEBUG [PyAMS (content.es)][MainThread] Starting content indexer process ... - Starting server in PID 23253. - Serving on http://0.0.0.0:6543 - -From this point, you can launch a browser and open URL *http://127.0.0.1:6543/admin* to get access to PyAMS -management interface; default login is "admin/admin", that you may change as soon as possible... diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/modules.rst --- a/docs/source/modules.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,9 +0,0 @@ -.. _modules: - -Modules list -============ - -.. toctree:: - :maxdepth: 4 - - pyams_utils diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.interfaces.rst --- a/docs/source/pyams_utils.interfaces.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ -pyams_utils.interfaces package -============================== - -Submodules ----------- - -pyams_utils.interfaces.data module ----------------------------------- - -.. automodule:: pyams_utils.interfaces.data - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.intids module ------------------------------------- - -.. automodule:: pyams_utils.interfaces.intids - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.site module ----------------------------------- - -.. automodule:: pyams_utils.interfaces.site - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.size module ----------------------------------- - -.. automodule:: pyams_utils.interfaces.size - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.tales module ------------------------------------ - -.. automodule:: pyams_utils.interfaces.tales - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.text module ----------------------------------- - -.. automodule:: pyams_utils.interfaces.text - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.timezone module --------------------------------------- - -.. automodule:: pyams_utils.interfaces.timezone - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.traversing module ----------------------------------------- - -.. automodule:: pyams_utils.interfaces.traversing - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.tree module ----------------------------------- - -.. automodule:: pyams_utils.interfaces.tree - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.interfaces.zeo module ---------------------------------- - -.. automodule:: pyams_utils.interfaces.zeo - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.interfaces - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.protocol.rst --- a/docs/source/pyams_utils.protocol.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -pyams_utils.protocol package -============================ - -Submodules ----------- - -pyams_utils.protocol.http module --------------------------------- - -.. automodule:: pyams_utils.protocol.http - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.protocol.xmlrpc module ----------------------------------- - -.. automodule:: pyams_utils.protocol.xmlrpc - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.protocol - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.rst --- a/docs/source/pyams_utils.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,267 +0,0 @@ -pyams_utils package -=================== - -Subpackages ------------ - -.. toctree:: - - pyams_utils.interfaces - pyams_utils.protocol - pyams_utils.scripts - pyams_utils.tests - pyams_utils.timezone - pyams_utils.widget - pyams_utils.zmi - -Submodules ----------- - -pyams_utils.adapter module --------------------------- - -.. automodule:: pyams_utils.adapter - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.attr module ------------------------ - -.. automodule:: pyams_utils.attr - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.container module ----------------------------- - -.. automodule:: pyams_utils.container - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.context module --------------------------- - -.. automodule:: pyams_utils.context - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.data module ------------------------ - -.. automodule:: pyams_utils.data - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.date module ------------------------ - -.. automodule:: pyams_utils.date - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.decorator module ----------------------------- - -.. automodule:: pyams_utils.decorator - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.encoding module ---------------------------- - -.. automodule:: pyams_utils.encoding - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.html module ------------------------ - -.. automodule:: pyams_utils.html - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.i18n module ------------------------ - -.. automodule:: pyams_utils.i18n - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.include module --------------------------- - -.. automodule:: pyams_utils.include - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.intids module -------------------------- - -.. automodule:: pyams_utils.intids - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.list module ------------------------ - -.. automodule:: pyams_utils.list - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.lock module ------------------------ - -.. automodule:: pyams_utils.lock - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.progress module ---------------------------- - -.. automodule:: pyams_utils.progress - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.property module ---------------------------- - -.. automodule:: pyams_utils.property - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.registry module ---------------------------- - -.. automodule:: pyams_utils.registry - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.request module --------------------------- - -.. automodule:: pyams_utils.request - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.schema module -------------------------- - -.. automodule:: pyams_utils.schema - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.session module --------------------------- - -.. automodule:: pyams_utils.session - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.site module ------------------------ - -.. automodule:: pyams_utils.site - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.size module ------------------------ - -.. automodule:: pyams_utils.size - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.tales module ------------------------- - -.. automodule:: pyams_utils.tales - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.text module ------------------------ - -.. automodule:: pyams_utils.text - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.traversing module ------------------------------ - -.. automodule:: pyams_utils.traversing - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.unicode module --------------------------- - -.. automodule:: pyams_utils.unicode - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.url module ----------------------- - -.. automodule:: pyams_utils.url - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.vocabulary module ------------------------------ - -.. automodule:: pyams_utils.vocabulary - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.wsgi module ------------------------ - -.. automodule:: pyams_utils.wsgi - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.zodb module ------------------------ - -.. automodule:: pyams_utils.zodb - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.scripts.rst --- a/docs/source/pyams_utils.scripts.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ -pyams_utils.scripts package -=========================== - -Submodules ----------- - -pyams_utils.scripts.zodb module -------------------------------- - -.. automodule:: pyams_utils.scripts.zodb - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.scripts - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.tests.rst --- a/docs/source/pyams_utils.tests.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -pyams_utils.tests package -========================= - -Submodules ----------- - -pyams_utils.tests.test_utilsdocs module ---------------------------------------- - -.. automodule:: pyams_utils.tests.test_utilsdocs - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.tests.test_utilsdocstrings module ---------------------------------------------- - -.. automodule:: pyams_utils.tests.test_utilsdocstrings - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.tests - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.timezone.rst --- a/docs/source/pyams_utils.timezone.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -pyams_utils.timezone package -============================ - -Submodules ----------- - -pyams_utils.timezone.utility module ------------------------------------ - -.. automodule:: pyams_utils.timezone.utility - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.timezone.vocabulary module --------------------------------------- - -.. automodule:: pyams_utils.timezone.vocabulary - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.timezone - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.widget.rst --- a/docs/source/pyams_utils.widget.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ -pyams_utils.widget package -========================== - -Submodules ----------- - -pyams_utils.widget.decimal module ---------------------------------- - -.. automodule:: pyams_utils.widget.decimal - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.widget - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/pyams_utils.zmi.rst --- a/docs/source/pyams_utils.zmi.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -pyams_utils.zmi package -======================= - -Submodules ----------- - -pyams_utils.zmi.intids module ------------------------------ - -.. automodule:: pyams_utils.zmi.intids - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.zmi.timezone module -------------------------------- - -.. automodule:: pyams_utils.zmi.timezone - :members: - :undoc-members: - :show-inheritance: - -pyams_utils.zmi.zeo module --------------------------- - -.. automodule:: pyams_utils.zmi.zeo - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: pyams_utils.zmi - :members: - :undoc-members: - :show-inheritance: diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/site.rst --- a/docs/source/site.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,73 +0,0 @@ -.. _site: - -PyAMS site management -===================== - -PyAMS site management is based on the ZODB. - -On application startup, if PyAMS_utils package is included into Pyramid configuration, several operations take -place: - - - a custom **site factory** is defined - - - custom request methods are defined - - - a custom **traverser** handling **namespaces** is defined - - - a custom subscribers predicate based on interfaces support is defined - - - several adapters are registered, to handle annotations and key references - - - custom TALES extensions are registered. - -The site factory is an important component in this process. It is this factory which will define the application root -and create a **local site manager**. - -Pyramid application is loaded from ZODB's root via a key defined in Pyramid's configuration file; the key is named -*pyams.application_name* and it's default value is *application*. - -If the application can't be found, PyAMS is looking for an application class name in Pyramid's configuration file; the -class name configuration key is called *pyams.application_factory* and defined by default as -*pyams_utils.site.BaseSiteRoot*. PyAMS default site factory will then create the application, and add a local site -manager to it (see :ref:`zca`). - -After application creation, a :py:class:`NewLocalSiteCreatedEvent ` is -notified. Custom packages can subscribe to this event to register custom components. - - -*pyams_upgrade* command line script ------------------------------------ - -Pyramid allows to define custom command line scripts for application management. A script called *pyams_upgrade* is -provided by PyAMS_utils package; this script apply the same process as PyAMS site factory, but can also be used to -manage **database generations**. The idea behind this is just to allow custom packages to provide a way to check and -upgrade database configuration away from application startup process: - -.. code-block:: bash - - # ./bin/pyams_upgrade webapp/development.ini - - -A **site generation checker** is just a named utility providing :py:class:`pyams_utils.interfaces.site.ISiteGenerations` -interface. For example, **pyams_security** package provides such utility, to make sure that local site manager -contains a PyAMS security manager and a principal annotation utility: - -.. code-block:: python - - from pyams_utils.site import check_required_utilities - - REQUIRED_UTILITIES = ((ISecurityManager, '', SecurityManager, 'Security manager'), - (IPrincipalAnnotationUtility, '', PrincipalAnnotationUtility, 'User profiles')) - - @utility_config(name='PyAMS security', provides=ISiteGenerations) - class SecurityGenerationsChecker(object): - """I18n generations checker""" - - generation = 1 - - def evolve(self, site, current=None): - """Check for required utilities""" - check_required_utilities(site, REQUIRED_UTILITIES) - -:py:func:`check_required_utilities ` is a PyAMS_utils utility function which -can to used to verify that a set of local utilities are correctly registered with the given names and interfaces. diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/tales.rst --- a/docs/source/tales.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,74 +0,0 @@ -.. _tales: - -Custom TALES extensions -======================= - -PyAMS defines a custom expression for TALES called *extension*. - -When this expression is encountered, the renderer is looking for an -:py:class:`ITALESExtension ` -multi-adapter for the current *context*, *request* and *view*, for the current -*context* and *request*, or only for the current *context*, in this order. -If an adapter is found, the renderer call it's :py:func:`render` method with -the expression parameters as input parameters. - -For example, the *metas* extension is an *ITALESExtension* adapter defined into -:py:mod:`pyams_skin.metas` module which can be used to include all required headers in -a page template. Extension is used like this in the page layout template: - -.. code-block:: html - - - -This extension is defined like this: - -.. code-block:: python - - from pyams_skin.interfaces.metas import IHTMLContentMetas - from pyams_utils.interfaces.tales import ITALESExtension - from pyramid.interfaces import IRequest - - from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter - - @adapter_config(name='metas', context=(Interface, IRequest, Interface), provides=ITALESExtension) - class MetasTalesExtension(ContextRequestViewAdapter): - '''extension:metas TALES extension''' - - def render(self, context=None): - if context is None: - context = self.context - result = [] - for name, adapter in sorted(self.request.registry.getAdapters((context, self.request, self.view), - IHTMLContentMetas), - key=lambda x: getattr(x[1], 'order', 9999)): - result.extend([meta.render() for meta in adapter.get_metas()]) - return '\n\t'.join(result) - -Some TALES extensions can require or accept arguments. For example, the *absolute_url* extension can accept -a context and a view name: - -.. code-block:: html - - - - - -The extension is defined like this: - -.. code-block:: python - - from persistent.interfaces import IPersistent - from pyams_utils.interfaces.tales import ITALESExtension - - from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter - from pyramid.url import resource_url - from zope.interface import Interface - - @adapter_config(name='absolute_url', context=(IPersistent, Interface, Interface), provides=ITALESExtension) - class AbsoluteUrlTalesExtension(ContextRequestViewAdapter): - '''extension:absolute_url(context, view_name) TALES extension''' - - def render(self, context=None, view_name=None): - if context is None: - context = self.context - return resource_url(context, self.request, view_name) diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/traverser.rst --- a/docs/source/traverser.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,47 +0,0 @@ -.. _traverser: - -PyAMS namespace traverser -========================= - -PyAMS_utils provide a custom URL traverser, defined in package :py:mod:`pyams_utils.traversing`. - -The :py:class:`NamespaceTraverser ` is a custom traverser based on default -Pyramid's *ResourceTreeAdapter*, but it adds the ability to use *namespaces*. Inherited from *Zope3* concept, a -namespace is a resource path element starting with the « *++* » characters, like this: - -.. code-block:: none - - http://localhost:5432/folder/content/++ns++argument/@@view.html - -In this sample, *ns* is the namespace name. When the traverser detects a namespace, it looks for several named -adapters (or multi-adapters) to the :py:class:`ITraversable ` interface -defined in *zope.traversing* package. Adapters lookup with name *ns* is done for the current *context* and *request*, -then only for the context and finally for the request, in this order. If a traversing adapter is found, it's -:py:func:`traverse` method is called, with the *attr* value as first argument, and the rest of the traversal stack -as second one. - -This is for example how a custom *etc* namespace traverser is defined: - -.. code-block:: python - - from pyams_utils.interfaces.site import ISiteRoot - from zope.traversing.interfaces import ITraversable - - from pyams_utils.adapter import adapter_config, ContextAdapter - - @adapter_config(name='etc', context=ISiteRoot, provides=ITraversable) - class SiteRootEtcTraverser(ContextAdapter): - """Site root ++etc++ namespace traverser""" - - def traverse(self, name, furtherpath=None): - if name == 'site': - return self.context.getSiteManager() - raise NotFound - -By using an URL like '++etc++site' on your site root, you can then get access to your local site manager. - -*argument* is not mandatory for the namespace traverser. If it is not provided, the *traverse* method is called with -an empty string (with is a default adapter name) as first argument. - -Several PyAMS components use custom traversal adapters. For example, getting thumbnails from an image is done -through a traversing adapter, which results in nicer URLs than when using classic URLs with arguments... diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/utilities.rst --- a/docs/source/utilities.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,57 +0,0 @@ -.. _utilities: - -Custom PyAMS utilities -====================== - -PyAMS_utils provides a small set of utilities. You can create some of them as global utilities registered in -the global components registry; other ones can be created manually by a site administrator and -are then registered automatically. - - -Server timezone ---------------- - -To manage timezones correctly, and display datetimes based on current server timezone, all datetimes should -be defined and stored in UTC. - -PyAMS_utils provides a :py:class:`ServerTimezoneUtility ` which -allows you to assign a default timezone to your server. - -To display a datetime with correct timezone, you can use the :py:func:`tztime ` function, -which assign server timezone to the given parameter: - -.. code-block:: python - - from datetime import datetime - from pyams_utils.timezone import tztime - - now = datetime.utcnow() - my_date = tztime(now) # converts *now* to server timezone - -We could imagine that datetimes could be displayed with current user timezone. But it's quite impossible to know -the user timazone from a server request. The only options are: - -- you ask an authenticated user to update a timezone setting in his profile - -- you can include Javascript libraries which will try to detect browser timezone from their computer configuration, and - do an AJAX request to update data in their session. - -That should require an update of :py:func:`tzinfo` adapter to get timezone info from session, request or user profile. - - -ZEO connection --------------- - -Several PyAMS utilities (like the tasks scheduler or the medias converter) are working with dedicated processes, -are connected to main PyAMS process through ØMQ, and use ZEO connections for their PyAMS database access. - -Clients of these processes have to send settings of the ZEO connections that they should use. - -The ZEOConnection utility can be created by the site manager through the web management interface (ZMI) from the -*Control panel*: - -.. image:: _static/zeo-add-menu.png - -ZEO connection creation form allows you to define all settings of a ZEO connection: - -.. image:: _static/zeo-add-form.png diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/zca.rst --- a/docs/source/zca.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,262 +0,0 @@ -.. _zca: - -Managing ZCA with PyAMS -======================= - -The **Zope Component Architecture** (aka ZCA) is used by the Pyramid framework "under the hood" to handle interfaces, -adapters and utilities. You don't **have to** use it in your own applications. But you can. - -The ZCA is mainly adding elements like **interfaces**, **adapters** and **utilities** to the Python language. It -allows you to write a framework or an application by using **components** which can be extended easily. - -You will find several useful resources about ZCA concepts on the internet. - - -Local utilities ---------------- - -In ZCA, a **utility** is a **registered** component which provides an **interface**. This interface is the -**contract** which defines features provided by the component which implements it. - -When a Pyramid application starts, a **global registry** is created to register a whole set of utilities and -adapters; this registration can be done via ZCML directives or via native Python code. -In addition, PyAMS allows you to define **local utilities**, which are stored and registered in the ZODB via a **site -manager**. - - -Defining site root ------------------- - -One of PyAMS pre-requisites is to use the ZODB, at least to store the site root application, it's configuration and a -set of local utilities. :ref:`site` describes application startup and **local site manager** -initialization process. - -This site can be used to store **local utilities** whose configuration, which is easily available to site -administrators through management interface, is stored in the ZODB. - - -Registering global utilities ----------------------------- - -**Global utilities** are components providing an interface which are registered in the global registry. -PyAMS_utils package provides custom annotations to register global utilities without using ZCML. For example, a skin -is nothing more than a simple utility providing the *ISkin* interface: - -.. code-block:: python - - from pyams_default_theme.layer import IPyAMSDefaultLayer - from pyams_skin.interfaces import ISkin - from pyams_utils.registry import utility_config - - @utility_config(name='PyAMS default skin', provides=ISkin) - class PyAMSDefaultSkin(object): - """PyAMS default skin""" - - label = _("PyAMS default skin") - layer = IPyAMSDefaultLayer - -This annotation registers a utility, named *PyAMS default skin*, providing the *ISkin* interface. It's the developer -responsibility to provide all attributes and methods required by the provided interface. - - -Registering local utilities ---------------------------- - -A local utility is a persistent object, registered in a *local site manager*, and providing a specific interface (if -a component provides several interfaces, it can be registered several times). - -Some components can be required by a given package, and created automatically via the *pyams_upgrade* command line -script; this process relies on the *ISiteGenerations* interface, for example for the timezone utility, a component -provided by PyAMS_utils package to handle server timezone and display times correctly: - -.. code-block:: python - - from pyams_utils.interfaces.site import ISiteGenerations - from pyams_utils.interfaces.timezone import IServerTimezone - - from persistent import Persistent - from pyams_utils.registry import utility_config - from pyams_utils.site import check_required_utilities - from pyramid.events import subscriber - from zope.container.contained import Contained - from zope.interface import implementer - from zope.schema.fieldproperty import FieldProperty - - @implementer(IServerTimezone) - class ServerTimezoneUtility(Persistent, Contained): - - timezone = FieldProperty(IServerTimezone['timezone']) - - REQUIRED_UTILITIES = ((IServerTimezone, '', ServerTimezoneUtility, 'Server timezone'),) - - @subscriber(INewLocalSite) - def handle_new_local_site(event): - """Create a new ServerTimezoneUtility when a site is created""" - site = event.manager.__parent__ - check_required_utilities(site, REQUIRED_UTILITIES) - - @utility_config(name='PyAMS timezone', provides=ISiteGenerations) - class TimezoneGenerationsChecker(object): - """Timezone generations checker""" - - generation = 1 - - def evolve(self, site, current=None): - """Check for required utilities""" - check_required_utilities(site, REQUIRED_UTILITIES) - -Some utilities can also be created manually by an administrator through the management interface, and registered -automatically after their creation. For example, this is how a ZEO connection utility (which is managing settings to -define a ZEO connection) is registered: - -.. code-block:: python - - from pyams_utils.interfaces.site import IOptionalUtility - from pyams_utils.interfaces.zeo import IZEOConnection - from zope.annotation.interfaces import IAttributeAnnotatable - from zope.lifecycleevent.interfaces import IObjectAddedEvent, IObjectRemovedEvent - - from persistent import Persistent - from pyramid.events import subscriber - from zope.container.contained import Contained - - @implementer(IZEOConnection) - class ZEOConnection(object): - """ZEO connection object. See source code to get full implementation...""" - - @implementer(IOptionalUtility, IAttributeAnnotatable) - class ZEOConnectionUtility(ZEOConnection, Persistent, Contained): - """Persistent ZEO connection utility""" - - @subscriber(IObjectAddedEvent, context_selector=IZEOConnection) - def handle_added_connection(event): - """Register new ZEO connection when added""" - manager = event.newParent - manager.registerUtility(event.object, IZEOConnection, name=event.object.name) - - @subscriber(IObjectRemovedEvent, context_selector=IZEOConnection) - def handle_removed_connection(event): - """Un-register ZEO connection when deleted""" - manager = event.oldParent - manager.unregisterUtility(event.object, IZEOConnection, name=event.object.name) - -*context_selector* is a custom subscriber predicate, so that subscriber event is activated only if object concerned -by an event is providing given interface. - - -Looking for utilities ---------------------- - -ZCA provides the *getUtility* and *queryUtility* functions to look for a utility. But these methods only applies to -global registry. - -PyAMS package provides equivalent functions, which are looking for components into local registry before looking into -the global one. For example: - -.. code-block:: python - - from pyams_security.interfaces import ISecurityManager - from pyams_utils.registry import query_utility - - manager = query_utility(ISecurityManager) - if manager is not None: - print("Manager is there!") - -All ZCA utility functions have been ported to use local registry: *registered_utilities*, *query_utility*, -*get_utility*, *get_utilities_for*, *get_all_utilities_registered_for* functions all follow the equivalent ZCA -functions API, but are looking for utilities in the local registry before looking in the global registry. - - -Registering adapters --------------------- - -An adapter is also a kind of utility. But instead of *just* providing an interface, it adapts an input object, -providing a given interface, to provide another interface. An adapter can also be named, so that you can choose which -adapter to use at a given time. - -PyAMS_utils provide another annotation, to help registering adapters without using ZCML files. An adapter can be a -function which directly returns an object providing the requested interface, or an object which provides the interface. - -The first example is an adapter which adapts any persistent object to get it's associated transaction manager: - -.. code-block:: python - - from persistent.interfaces import IPersistent - from transaction.interfaces import ITransactionManager - from ZODB.interfaces import IConnection - - from pyams_utils.adapter import adapter_config - - @adapter_config(context=IPersistent, provides=ITransactionManager) - def get_transaction_manager(obj): - conn = IConnection(obj) - try: - return conn.transaction_manager - except AttributeError: - return conn._txn_mgr - -This is another adapter which adapts any contained object to the *IPathElements* interface; this interface can be -used to build index that you can use to find objects based on a parent object: - -.. code-block:: python - - from pyams_utils.interfaces.traversing import IPathElements - from zope.intid.interfaces import IIntIds - from zope.location.interfaces import IContained - - from pyams_utils.adapter import ContextAdapter - from pyams_utils.registry import query_utility - from pyramid.location import lineage - - @adapter_config(context=IContained, provides=IPathElements) - class PathElementsAdapter(ContextAdapter): - """Contained object path elements adapter""" - - @property - def parents(self): - intids = query_utility(IIntIds) - if intids is None: - return [] - return [intids.register(parent) for parent in lineage(self.context)] - -An adapter can also be a multi-adapter, when several input objects are requested to provide a given interface. For -example, many adapters require a context and a request, eventually a view, to provide another feature. This is how, -for example, we define a custom *name* column in a security manager table displaying a list of plug-ins: - -.. code-block:: python - - from pyams_zmi.layer import IAdminLayer - from z3c.table.interfaces import IColumn - - from pyams_skin.table import I18nColumn - from z3c.table.column import GetAttrColumn - - @adapter_config(name='name', context=(Interface, IAdminLayer, SecurityManagerPluginsTable), provides=IColumn) - class SecurityManagerPluginsNameColumn(I18nColumn, GetAttrColumn): - """Security manager plugins name column""" - - _header = _("Name") - attrName = 'title' - weight = 10 - - -Registering vocabularies ------------------------- - -A **vocabulary** is a custom factory which can be used as source for several field types, like *choices* or *lists*. -Vocabularies have to be registered in a custom registry, so PyAMS_utils provide another annotation to register them. -This example is based on the *Timezone* component which allows you to select a timezone between a list of references: - -.. code-block:: python - - import pytz - from pyams_utils.vocabulary import vocabulary_config - from zope.schema.vocabulary import SimpleTerm, SimpleVocabulary - - @vocabulary_config(name='PyAMS timezones') - class TimezonesVocabulary(SimpleVocabulary): - """Timezones vocabulary""" - - def __init__(self, *args, **kw): - terms = [SimpleTerm(t, t, t) for t in pytz.all_timezones] - super(TimezonesVocabulary, self).__init__(terms) diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/zeo.rst --- a/docs/source/zeo.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,114 +0,0 @@ -.. _zeo: - -Creating a ZEO server -===================== - -PyAMS primarilly relies on a ZODB database to it's store itt's configuration. Other packages may rely on another -database, but *PyAMS_content* package also stores it's contents in a ZODB. - -As some PyAMS packages start concurrent processes ("synchronization" is done via **ØMQ**), concurrent accesses are -required on the ZODB (event when you start your application in "single process" mode) and a ZEO server have to be -started. - - -Creating initial buildout -------------------------- - -PyAMS provides a ZEO server scaffold, called *zeo_server*, generated via a *cookiecutter* template. - -A simple option to create a ZEO server is to create a buildout environment including *ZEO* and *ZODB* packages: - -.. code-block:: bash - - # mkdir /var/local/ - # pip3 install virtualenv - # virtualenv --python=python3.5 env - # cd env - # . bin/activate - (env) # pip3.5 install cookiecutter - (env) # cookiecutter hg+http://hg.ztfy.org/pyams/scaffolds/zeo_server - -*CookieCutter* will ask you for a small set of input variables that you can change or not: - -- **pyams_release**: version of PyAMS configuration file to use. "latest" (default value) will point to last release; - you can also choose to point to a given release ("0.1.4" for example) - -- **project_name**: current environment name in "human form" - -- **project_slug**: "technical" package name, based on project name - -- **eggs_directory**: relative or absolute path to directory containing downloaded eggs; this directory can be - shared with other projects ("eggs" as default) - -- **run_user**: user name under which Apache process will run ("www-data" as default) - -- **run_group**: group name under which Apache process will run ("www-data" as default) - -- **zeo_server_port**: listening port of ZEO server ("8100" as default) - -- **zeo_monitor_port**: listening port of ZEO monitor ("8101" as default) - -- **zeo_storage**: name of first ZEO storage; default value is based on project name - -- **use_zeo_auth**: specify if ZEO authentication should be used - -- **zeo_auth_user**: name of ZEO authenticated user (if ZEO authentication is used) - -- **zeo_auth_password**: password of ZEO authenticated user (if ZEO authentication is used) - -- **zeo_pack_report**: email address to which pack reports should be sent - -- **logs_directory**: absolute path to directory containing ZEO's log files. - -A message is displayed after initialization to finalize environment creation: - -.. code-block:: - - Your ZEO environment is initialized. - To finalize it's creation, just type: - - cd zeo_server - - python3.5 bootstrap.py - - ./bin/buildout - - To initialize authentication database, please run following command after buildout: - ./bin/zeopasswd -f etc/auth.db -p digest -r "ZEO_server" zeouser xxxx - - -ZEO server configuration ------------------------- - -All ZEO configuration files are generated in "etc" subdirectory. These includes: - -- **etc/zeo_server-zdaemon.conf**: ZDaemon configuration file - -- **etc/zeo_server-zeo.conf**: ZEO server configuration file - -- **etc/auth.db**: ZEO authentication file; WARNING: this file is not created automatically, you have to create it - after buildout. - -In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during -*CookieCutter* template creation. - - -ZEO server tools ----------------- - -A set of system configuration files are produced to handle your ZEO environment. These includes: - -- **etc/init.d/zeo-zeo_server**: ZEO server start/stop script in Init-D format. Create a link to this file in - */etc/init.d* and update Init.d scripts (*update-rc.d zeo-zeo_server defaults*) to include ZEO in server start/stop - process. You can also use this script to start/stop ZEO by hand with *start* and *stop* arguments. - -- **etc/systemd/zeo-zeo_server.service**: SystemD service configuration file for ZEO server. Create a link to this - file in */etc/systemd/system* and reload SystemD daemon (*systemctl daemon-reload*) before activating ZEO service - (*systemctl enable zeo-zeo_server.service* and *systemctl start zeo-zeo_server.service*). - -- **etc/logrotate.d/zeo-zeo_server**: LogRotate configuration file for ZEO log files. Create a link to this file in - */etc/logrotate.d* to activate log rotation for ZEO server. - -- **etc/cron.d/pack-zeo-zeo_server**: Cron configuration file for ZEO database packing. Just create a link to this - file in */etc/cron.d* directory to enable ZODB packing on a weekly basis (by default). - -In these file names, always replace "zeo_server" with the value which was given to "project_slug" variable during -*CookieCutter* template creation. All directory names are those used on a Debian GNU/Linux distribution and may have -to be changed on other distributions. diff -r 53dc81f933ed -r 985534bc6ab9 setup.py --- a/setup.py Thu Jan 11 16:57:23 2018 +0100 +++ b/setup.py Sun Jan 14 15:01:21 2018 +0100 @@ -25,7 +25,7 @@ README = os.path.join(DOCS, 'README.txt') HISTORY = os.path.join(DOCS, 'HISTORY.txt') -version = '0.1.9' +version = '0.1.10' long_description = open(README).read() + '\n\n' + open(HISTORY).read() tests_require = [ diff -r 53dc81f933ed -r 985534bc6ab9 src/pyams_utils.egg-info/PKG-INFO --- a/src/pyams_utils.egg-info/PKG-INFO Thu Jan 11 16:57:23 2018 +0100 +++ b/src/pyams_utils.egg-info/PKG-INFO Sun Jan 14 15:01:21 2018 +0100 @@ -1,11 +1,12 @@ Metadata-Version: 1.1 Name: pyams-utils -Version: 0.1.9 +Version: 0.1.10 Summary: Utility functions and classes for PyAMS Home-page: http://www.ztfy.org Author: Thierry Florac Author-email: tflorac@ulthar.net License: ZPL +Description-Content-Type: UNKNOWN Description: =================== pyams_utils package =================== @@ -47,6 +48,12 @@ Changelog ========= + 0.1.10 + ------ + - added ZODB connection class and vocabulary based on Pyramid's settings + - updated DocFieldProperty to correctly handle attributes documentation + - small updates in registry management functions + 0.1.9 ----- - added "NullAdapter" class to be able to remove a default adapter for a given context diff -r 53dc81f933ed -r 985534bc6ab9 src/pyams_utils.egg-info/SOURCES.txt --- a/src/pyams_utils.egg-info/SOURCES.txt Thu Jan 11 16:57:23 2018 +0100 +++ b/src/pyams_utils.egg-info/SOURCES.txt Sun Jan 14 15:01:21 2018 +0100 @@ -1,159 +1,7 @@ MANIFEST.in setup.py docs/HISTORY.txt -docs/Makefile docs/README.txt -docs/make.bat -docs/build/Makefile -docs/build/make.bat -docs/build/doctrees/environment.pickle -docs/build/doctrees/index.doctree -docs/build/doctrees/install.doctree -docs/build/doctrees/modules.doctree -docs/build/doctrees/pyams_utils.doctree -docs/build/doctrees/pyams_utils.interfaces.doctree -docs/build/doctrees/pyams_utils.protocol.doctree -docs/build/doctrees/pyams_utils.scripts.doctree -docs/build/doctrees/pyams_utils.tests.doctree -docs/build/doctrees/pyams_utils.timezone.doctree -docs/build/doctrees/pyams_utils.widget.doctree -docs/build/doctrees/pyams_utils.zmi.doctree -docs/build/doctrees/site.doctree -docs/build/doctrees/tales.doctree -docs/build/doctrees/traverser.doctree -docs/build/doctrees/utilities.doctree -docs/build/doctrees/zca.doctree -docs/build/doctrees/zeo.doctree -docs/build/html/.buildinfo -docs/build/html/genindex.html -docs/build/html/index.html -docs/build/html/install.html -docs/build/html/modules.html -docs/build/html/objects.inv -docs/build/html/py-modindex.html -docs/build/html/pyams_utils.html -docs/build/html/pyams_utils.interfaces.html -docs/build/html/pyams_utils.protocol.html -docs/build/html/pyams_utils.scripts.html -docs/build/html/pyams_utils.tests.html -docs/build/html/pyams_utils.timezone.html -docs/build/html/pyams_utils.widget.html -docs/build/html/pyams_utils.zmi.html -docs/build/html/search.html -docs/build/html/searchindex.js -docs/build/html/searchindex.min.js -docs/build/html/site.html -docs/build/html/tales.html -docs/build/html/traverser.html -docs/build/html/utilities.html -docs/build/html/zca.html -docs/build/html/zeo.html -docs/build/html/_images/zeo-add-form.png -docs/build/html/_images/zeo-add-menu.png -docs/build/html/_sources/index.rst.txt -docs/build/html/_sources/index.txt -docs/build/html/_sources/install.rst.txt -docs/build/html/_sources/install.txt -docs/build/html/_sources/modules.rst.txt -docs/build/html/_sources/modules.txt -docs/build/html/_sources/pyams_utils.interfaces.rst.txt -docs/build/html/_sources/pyams_utils.interfaces.txt -docs/build/html/_sources/pyams_utils.protocol.rst.txt -docs/build/html/_sources/pyams_utils.protocol.txt -docs/build/html/_sources/pyams_utils.rst.txt -docs/build/html/_sources/pyams_utils.scripts.rst.txt -docs/build/html/_sources/pyams_utils.scripts.txt -docs/build/html/_sources/pyams_utils.tests.rst.txt -docs/build/html/_sources/pyams_utils.tests.txt -docs/build/html/_sources/pyams_utils.timezone.rst.txt -docs/build/html/_sources/pyams_utils.timezone.txt -docs/build/html/_sources/pyams_utils.txt -docs/build/html/_sources/pyams_utils.widget.rst.txt -docs/build/html/_sources/pyams_utils.widget.txt -docs/build/html/_sources/pyams_utils.zmi.rst.txt -docs/build/html/_sources/pyams_utils.zmi.txt -docs/build/html/_sources/site.rst.txt -docs/build/html/_sources/site.txt -docs/build/html/_sources/tales.rst.txt -docs/build/html/_sources/tales.txt -docs/build/html/_sources/traverser.rst.txt -docs/build/html/_sources/traverser.txt -docs/build/html/_sources/utilities.rst.txt -docs/build/html/_sources/utilities.txt -docs/build/html/_sources/zca.rst.txt -docs/build/html/_sources/zca.txt -docs/build/html/_sources/zeo.rst.txt -docs/build/html/_static/ajax-loader.gif -docs/build/html/_static/basic.css -docs/build/html/_static/basic.min.css -docs/build/html/_static/comment-bright.png -docs/build/html/_static/comment-close.png -docs/build/html/_static/comment.png -docs/build/html/_static/dialog-note.png -docs/build/html/_static/dialog-seealso.png -docs/build/html/_static/dialog-todo.png -docs/build/html/_static/dialog-topic.png -docs/build/html/_static/dialog-warning.png -docs/build/html/_static/doctools.js -docs/build/html/_static/doctools.min.js -docs/build/html/_static/down-pressed.png -docs/build/html/_static/down.png -docs/build/html/_static/epub.css -docs/build/html/_static/file.png -docs/build/html/_static/footerbg.png -docs/build/html/_static/headerbg.png -docs/build/html/_static/ie6.css -docs/build/html/_static/ie6.min.css -docs/build/html/_static/ie6.min.min.css -docs/build/html/_static/jquery-1.11.1.js -docs/build/html/_static/jquery-1.11.1.min.js -docs/build/html/_static/jquery-1.11.1.min.min.js -docs/build/html/_static/jquery-3.1.0.js -docs/build/html/_static/jquery.js -docs/build/html/_static/jquery.min.js -docs/build/html/_static/jquery.min.min.js -docs/build/html/_static/middlebg.png -docs/build/html/_static/minus.png -docs/build/html/_static/plus.png -docs/build/html/_static/pygments.css -docs/build/html/_static/pygments.min.css -docs/build/html/_static/pyramid.css -docs/build/html/_static/pyramid.min.css -docs/build/html/_static/searchtools.js -docs/build/html/_static/searchtools.min.js -docs/build/html/_static/transparent.gif -docs/build/html/_static/underscore-1.3.1.js -docs/build/html/_static/underscore-1.3.1.min.js -docs/build/html/_static/underscore.js -docs/build/html/_static/underscore.min.js -docs/build/html/_static/underscore.min.min.js -docs/build/html/_static/up-pressed.png -docs/build/html/_static/up.png -docs/build/html/_static/websupport.js -docs/build/html/_static/websupport.min.js -docs/build/html/_static/websupport.min.min.js -docs/build/html/_static/zeo-add-form.png -docs/build/html/_static/zeo-add-menu.png -docs/source/conf.py -docs/source/index.rst -docs/source/install.rst -docs/source/modules.rst -docs/source/pyams_utils.interfaces.rst -docs/source/pyams_utils.protocol.rst -docs/source/pyams_utils.rst -docs/source/pyams_utils.scripts.rst -docs/source/pyams_utils.tests.rst -docs/source/pyams_utils.timezone.rst -docs/source/pyams_utils.widget.rst -docs/source/pyams_utils.zmi.rst -docs/source/site.rst -docs/source/tales.rst -docs/source/traverser.rst -docs/source/utilities.rst -docs/source/zca.rst -docs/source/zeo.rst -docs/source/_static/zeo-add-form.png -docs/source/_static/zeo-add-menu.png src/pyams_utils/__init__.py src/pyams_utils/adapter.py src/pyams_utils/attr.py diff -r 53dc81f933ed -r 985534bc6ab9 src/pyams_utils/locales/fr/LC_MESSAGES/pyams_utils.po --- a/src/pyams_utils/locales/fr/LC_MESSAGES/pyams_utils.po Thu Jan 11 16:57:23 2018 +0100 +++ b/src/pyams_utils/locales/fr/LC_MESSAGES/pyams_utils.po Sun Jan 14 15:01:21 2018 +0100 @@ -4,7 +4,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE 1.0\n" -"POT-Creation-Date: 2017-10-10 15:56+0200\n" +"POT-Creation-Date: 2018-01-11 16:58+0100\n" "PO-Revision-Date: 2015-01-18 01:01+0100\n" "Last-Translator: Thierry Florac \n" "Language-Team: French\n" diff -r 53dc81f933ed -r 985534bc6ab9 src/pyams_utils/locales/pyams_utils.pot --- a/src/pyams_utils/locales/pyams_utils.pot Thu Jan 11 16:57:23 2018 +0100 +++ b/src/pyams_utils/locales/pyams_utils.pot Sun Jan 14 15:01:21 2018 +0100 @@ -1,12 +1,12 @@ # # SOME DESCRIPTIVE TITLE # This file is distributed under the same license as the PACKAGE package. -# FIRST AUTHOR , 2017. +# FIRST AUTHOR , 2018. #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE 1.0\n" -"POT-Creation-Date: 2017-10-10 15:56+0200\n" +"POT-Creation-Date: 2018-01-11 16:58+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n"