ó ÿgdSc@sdZddlZddlZddlZddlmZddlmZm Z ddl m Z ddl m Z ddlmZddlmZdd lmZdd lmZdd lmZdd lmZmZdd lmZdefd„ƒYZdS(sË sphinx.websupport ~~~~~~~~~~~~~~~~~ Base Module for web support functions. :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. iÿÿÿÿN(tpath(t EnvironmenttFileSystemLoader(t publish_parts(tSphinx(t_(t ensuredir(tdumps(t htmlescape(terrors(t BaseSearchtSEARCH_ADAPTERS(tStorageBackendt WebSupportcBseZdZdddddddejejdeddd„ Zd„Z d„Z d„Z d„Z d„Z ded „Zd „Zded „Zded „Zddeddded „Zd„Zd„Zed„Zd„Zd„Zd„Zd„ZRS(s‡The main API class for the web support package. All interactions with the web support package should occur through this class. ttstaticcCsø||_||_tj|dƒ|_|p3|j|_|pQtj|jdƒ|_|potj|jdƒ|_| jdƒ|_ | jdƒ|_ ||_ | |_ | |_ | |_|jƒ|j|ƒ|j|ƒd|_|jƒdS(NtdataRtdoctreest/(tsrcdirtbuilddirRtjointoutdirtdatadirt staticdirt doctreedirtstript staticroottdocroottstatustwarningtmoderation_callbacktallow_anonymous_commentst_init_templatingt _init_searcht _init_storagetNonet_globalcontextt_make_base_comment_options(tselfRRRRRtsearchtstorageRRRR RR((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyt__init__#s"          cCs|t|tƒr||_n]ddlm}|sitj|jddƒ}ttj |ƒƒd|}n||ƒ|_dS(Niÿÿÿÿ(tSQLAlchemyStoragetdbs websupport.dbs sqlite:///( t isinstanceR R)t+sphinx.websupport.storage.sqlalchemystorageR+RRRRtdirname(R'R)R+tdb_path((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyR#Js  cCsFddl}tj|jddƒ}t|ƒ}td|ƒ|_dS(Niÿÿÿÿtthemestbasictloader(tsphinxRRt package_dirRRt template_env(R'R4t template_pathR3((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyR!Ys     cCs™t|tƒr||_net|p'd\}}d|}tt|dd|gƒ|ƒ}tj|j dƒ}||ƒ|_|j j dƒ|_ dS(Ntnullssphinx.websupport.search.R(ssearchresults.html( R-R R(R tgetattrt __import__R$RRRR6t get_templatetresults_template(R'R(tmodtclst SearchClasst search_path((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyR"`s  !c Cs›|jstdƒ‚nt|j|j|j|jdd|jd|jƒ}|jj|j |j |j |j ƒ|j j ƒ|jƒ|j jƒdS(s•Build the documentation. Places the data into the `outdir` directory. Use it like this:: support = WebSupport(srcdir, builddir, search='xapian') support.build() This will read reStructured text files from `srcdir`. Then it will build the pickles and search index, placing them into `builddir`. It will also save node data to the database. s+No srcdir associated with WebSupport objectt websupportRRN(Rt RuntimeErrorRRRRRtbuildert set_webinfoRRR(R)t pre_buildtbuildt post_build(R'tapp((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRFls   cCs[|jsTtj|jdƒ}t|dƒ}ztj|ƒ|_Wd|jƒXn|jS(s,Load and return the "global context" pickle.sglobalcontext.pickletrbN(R%RRRtopentpickletloadtclose(R't infilenametf((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pytget_globalcontext‚s c Csütj|jd|ƒ}tj|ƒrM|d}|s@d}qW|d7}n |d}yt|dƒ}Wn$tk rtjd|ƒ‚nXztj |ƒ}Wd|j ƒX|j ||ƒ}|j |j j||ƒƒ} || |d |d <|S( sLoad and return a document from a pickle. The document will be a dict object which can be used to render a template:: support = WebSupport(datadir=datadir) support.get_document('index', username, moderator) In most cases `docname` will be taken from the request path and passed directly to this function. In Flask, that would be something like this:: @app.route('/') def index(docname): username = g.user.name if g.user else '' moderator = g.user.moderator if g.user else False try: document = support.get_document(docname, username, moderator) except DocumentNotFoundError: abort(404) render_template('doc.html', document=document) The document dict that is returned contains the following items to be used during template rendering. * **body**: The main body of the document as HTML * **sidebar**: The sidebar of the document as HTML * **relbar**: A div containing links to related documents * **title**: The title of the document * **css**: Links to css files used by Sphinx * **script**: Javascript containing comment options This raises :class:`~sphinx.websupport.errors.DocumentNotFoundError` if a document matching `docname` is not found. :param docname: the name of the document to load. tpickless/index.fpickletindexs/indexs.fpickleRIs$The document "%s" could not be foundNtscript(RRRtisdirRJtIOErrorR tDocumentNotFoundErrorRKRLRMt_make_comment_optionst_make_metadataR)t get_metadata( R'tdocnametusernamet moderatortdocpathRNROtdocumentt comment_optst comment_meta((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyt get_documents(%      cCsm|jj|ƒ}i|d6td6|d6dd6td6}i|jj|ƒd6dd 6d d 6d d 6}|S( s2Perform a search for the query `q`, and create a set of search results. Then render the search results as html and return a context dict like the one created by :meth:`get_document`:: document = support.get_search_results(q) :param q: the search query tqtsearch_performedtsearch_resultss../RRtbodysSearch ResultsttitleRtsidebartrelbar(R(tquerytTrueRR<trender(R'RbtresultstctxR^((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pytget_search_resultsÍs   cCs|jj|||ƒS(s Get the comments and source associated with `node_id`. If `username` is given vote information will be included with the returned comments. The default CommentBackend returns a dict with two keys, *source*, and *comments*. *source* is raw source of the node and is used as the starting point for proposals a user can add. *comments* is a list of dicts that represent a comment, each having the following items: ============= ====================================================== Key Contents ============= ====================================================== text The comment text. username The username that was stored with the comment. id The comment's unique identifier. rating The comment's current rating. age The time in seconds since the comment was added. time A dict containing time information. It contains the following keys: year, month, day, hour, minute, second, iso, and delta. `iso` is the time formatted in ISO 8601 format. `delta` is a printable form of how old the comment is (e.g. "3 hours ago"). vote If `user_id` was given, this will be an integer representing the vote. 1 for an upvote, -1 for a downvote, or 0 if unvoted. node The id of the node that the comment is attached to. If the comment's parent is another comment rather than a node, this will be null. parent The id of the comment that this comment is attached to if it is not attached to a node. children A list of all children, in this format. proposal_diff An HTML representation of the differences between the the current source and the user's proposed source. ============= ====================================================== :param node_id: the id of the node to get comments for. :param username: the username of the user viewing the comments. :param moderator: whether the user is a moderator. (R)tget_data(R'tnode_idR[R\((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRoçs'cCs|jj|||ƒS(stDelete a comment. If `moderator` is True, the comment and all descendants will be deleted from the database, and the function returns ``True``. If `moderator` is False, the comment will be marked as deleted (but not removed from the database so as not to leave any comments orphaned), but only if the `username` matches the `username` on the comment. The username and text files are replaced with "[deleted]" . In this case, the function returns ``False``. This raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError` if moderator is False and `username` doesn't match username on the comment. :param comment_id: the id of the comment to delete. :param username: the username requesting the deletion. :param moderator: whether the requestor is a moderator. (R)tdelete_comment(R't comment_idR[R\((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRqsc Cs‘|dkr-|jrd}q-tjƒ‚n|j|ƒ} |jj| |||||||ƒ} || d<| r|jr|j| ƒn| S(s9Add a comment to a node or another comment. Returns the comment in the same format as :meth:`get_comments`. If the comment is being attached to a node, pass in the node's id (as a string) with the node keyword argument:: comment = support.add_comment(text, node_id=node_id) If the comment is the child of another comment, provide the parent's id (as a string) with the parent keyword argument:: comment = support.add_comment(text, parent_id=parent_id) If you would like to store a username with the comment, pass in the optional `username` keyword argument:: comment = support.add_comment(text, node=node_id, username=username) :param parent_id: the prefixed id of the comment's parent. :param text: the text of the comment. :param displayed: for moderation purposes :param username: the username of the user making the comment. :param time: the time the comment was created, defaults to now. t Anonymoust original_textN(R$R R tUserNotAuthorizedErrort_parse_comment_textR)t add_commentR( R'ttextRpt parent_idt displayedR[ttimetproposalR\tparsedtcomment((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRw&s      cCsUt|ƒ}d|ko#dkns;td|ƒ‚n|jj|||ƒdS(sProcess a user's vote. The web support package relies on the API user to perform authentication. The API user will typically receive a comment_id and value from a form, and then make sure the user is authenticated. A unique username must be passed in, which will also be used to retrieve the user's past voting data. An example, once again in Flask:: @app.route('/docs/process_vote', methods=['POST']) def process_vote(): if g.user is None: abort(401) comment_id = request.form.get('comment_id') value = request.form.get('value') if value is None or comment_id is None: abort(400) support.process_vote(comment_id, g.user.name, value) return "success" :param comment_id: the comment being voted on :param username: the unique username of the user voting :param value: 1 for an upvote, -1 for a downvote, 0 for an unvote. iÿÿÿÿis"vote value %s out of range (-1, 1)N(tintt ValueErrorR)t process_vote(R'RrR[tvalue((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyROs cCs|jj||ƒdS(sôTo remain decoupled from a webapp's authentication system, the web support package stores a user's username with each of their comments and votes. If the authentication system allows a user to change their username, this can lead to stagnate data in the web support system. To avoid this, each time a username is changed, this method should be called. :param old_username: The original username. :param new_username: The new username. N(R)tupdate_username(R't old_usernamet new_username((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRƒks cCs)|stjƒ‚n|jj|ƒdS(s6Accept a comment that is pending moderation. This raises :class:`~sphinx.websupport.errors.UserNotAuthorizedError` if moderator is False. :param comment_id: The id of the comment that was accepted. :param moderator: Whether the user making the request is a moderator. N(R RuR)taccept_comment(R'RrR\((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyR†xs c CsÕi|_|jdkrgd d!d"d#d$g}x7|D],\}}d tj|j|ƒ|j| var COMMENT_OPTIONS = %s; (RštcopytupdateRjt dump_json(R'R[R\trv((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRW¦s cCsdt|ƒS(Nse (R¢(R'R((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRXºscCs_itd6td6dd6}y t|ddd|ƒd}Wntk rZt|ƒ}nX|S( Ntfile_insertion_enabledt raw_enabledtunicodetoutput_encodingt writer_namethtmltsettings_overridestfragment(tFalseRt ExceptionR(R'Rxtsettingstret((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyRvÁs   N(t__name__t __module__t__doc__R$tsyststdouttstderrRjR*R#R!R"RFRPR¬RaRnRoRqRwRRƒR†R&RWRXRv(((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyR sB     @ )   '  !  ( R²R³tcPickleRKR›tosRtjinja2RRt docutils.coreRtsphinx.applicationRt sphinx.localeRtsphinx.util.osutilRtsphinx.util.jsonimplRR¢tsphinx.util.pycompatRtsphinx.websupportR tsphinx.websupport.searchR R tsphinx.websupport.storageR tobjectR (((sD/usr/local/lib/python2.7/site-packages/sphinx/websupport/__init__.pyt s