From 646d67c1f3e33aa83dcfecb36a98a90f98589277 Mon Sep 17 00:00:00 2001 From: Brian Skinn Date: Tue, 10 Nov 2020 16:19:01 -0500 Subject: [PATCH 1/4] Generalize priority in data line regex Also add custom MDN inventory with non-integer priority values. Fixes #147 --- src/sphobjinv/inventory.py | 2 +- src/sphobjinv/re.py | 2 +- tests/resource/objects_mdn.inv | Bin 0 -> 6024 bytes 3 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 tests/resource/objects_mdn.inv diff --git a/src/sphobjinv/inventory.py b/src/sphobjinv/inventory.py index ad490193..5c55d457 100644 --- a/src/sphobjinv/inventory.py +++ b/src/sphobjinv/inventory.py @@ -565,7 +565,7 @@ def _general_import(self): import_errors = { SourceTypes.BytesPlaintext: TypeError, SourceTypes.BytesZlib: (zlib_error, TypeError), - SourceTypes.FnamePlaintext: (OSError, TypeError), + SourceTypes.FnamePlaintext: (OSError, TypeError, UnicodeDecodeError), SourceTypes.FnameZlib: (OSError, TypeError, zlib_error), SourceTypes.DictJSON: (ValidationError), } diff --git a/src/sphobjinv/re.py b/src/sphobjinv/re.py index 9e525f7b..ac639f94 100644 --- a/src/sphobjinv/re.py +++ b/src/sphobjinv/re.py @@ -77,7 +77,7 @@ : # Dividing colon (?P<{2}>\w+) # --> Role \s+ # Dividing space - (?P<{3}>-?\d+) # --> Priority + (?P<{3}>\S+) # --> Priority \s+ # Dividing space (?P<{4}>\S+) # --> URI \s+ # Dividing space diff --git a/tests/resource/objects_mdn.inv b/tests/resource/objects_mdn.inv new file mode 100644 index 0000000000000000000000000000000000000000..3edaf69363df5ab9d02146b1c484719f137b722b GIT binary patch literal 6024 zcmV;37kB6*AX9K?X>NERX>N99Zgg*Qc_4OWa&u{KZXhxWBOp+6Z)#;@bUGkyWNr#0 zAXa5^b7^mGIv_DFFbX3eRA^-&a%F8{X>Md?av*PJAarPHb0B7EY-J#6b0A}HZE$jB zb8}^6Aa!$TZf78RY-wUH3V7O`UCnmfxN_d>DQ2Oq)RynfoSUq!M$>YX*pi}_XEG

su^kYAs4&qYw z!}!ym@?Z91-1Y09-dz6EPuCikL1LuVRpbqo!e0ih(S!6A_$#SXT9p zCOH{q>8he@#!4__UmZxieh#XouG-dq0#hvxaB=o)HCDeh;v24(pe(-qrRmn$>w`uk zyEt2^*L7QHTgMk^o@GP}Ttu-ci@@d3Pl3Lz7@wPcZhIQE@FI%yp=sMjin{OClHn#0 zT1TfUlBZiK$?Usv$MKAeVy%kBT@^}tdu-c3L^UwfAf~v!6$qXY(VP=YIgyNi?T-WZ zWmbk*vcQs&g)OjcYQb2a5nY@;y!;lr`t&b{-6iuZd|^OqLZq_G9QXzL4#_Uhi~2E&>zGwp6=C1 z%;=zijFw-8tcT_>_QM=i03GzL#ir?mLo{5G5GwHNL12S-EGMJib(--eZTnARyL>$W zdmQ_fGF4=f7Pkme&zvK`AU?r!@1q3@IxYTCxn+gyQFg;Dd1Ep!lK9yKgDug8rF zIYW)NbwxW$PJ}tfPVSlwP4Y6LYzMw@2c~rVd$_k8j*|9Rj6gM{7#Vw+HX|h*@4B^k zeb|t%fO5=k3e1LO4Pt$)#Z$B0(e>~IfzqV`}MIE;lqFF`&Lxl ztX`_UF0PXr*~QuKqWVJi(?;G`_hg4a6W$;WZN*J_UP$mr`*yTo;D|N$9}jA*yQw7e zMhGDJ@B43MeguH&EZB;C^#4W{6J|pQfm6{WHN#NlADTT~@MkSy7^|@wn5vFqhPy;w zIAAV~8=kpNx(bzn338+~LwAO_I9m=wKfvxWR`nOWqA;+<$_Tk0S?G*rRvLGgL)ESO zyc)G+;Uq-EfBtO#{rNL4Rd8mM+`mFCbh@|H8?4~s?Ebiav5Tg(=h^4e6S&2}3EYhh z(^Ln9T-1VhtA|qaMX~2rc!_SXR^V+5f3K;nx|dX4>BkNsk)L1?(s&7X-S{_Vruf)& zLg>#TRF4hIu{B@*tQt4PFFjRqd}_+Sp37 z$=3#2xQIgFe3Mp*szbbrnywBbA*y{}ja*wUJd{CszRdv|~L{0CbEjC58*O&!K!{M12=HMh+x3Uq{_#tJXa4F8T<*bx(a+xK6N zhj(He#bD=oTnh+=eHUidwZ03ObE(0XBF4ejGqEr2*0tB1KON;{br$@!P^+28hDyJy zBnY0+-;iO*x}ypa>Mr#;rf6>PW4%l|{BK|8V*fd1FQlxtEX#|D62ANJTqHRVNoOrLQv?IIp_ri;_ccN2M z`$##%sJZnHRB2!Ua$?$`3*_dESRf*ZvMOw{fdQ9dQd3-HvQwO&fF{E~Ijo>-MkpwS zkq-WW^X?DKf`DBOka+dr3%8+UWfW_VgMXg1x3NFGKr$bzhlOfjUYJ5C9ZmOzp=t@W zoExjQsU@?Vb3%f*Q8S5bzH`BTFJ+i@-}VDfwPK1(_?@2TyiU?ND>-J@Wa#asZh;R^<9vKlY)!f1ud2jotmj1f6X}wm+gUvkk}^fkPe8MxenQ%toL= zwEdPs=*JGRQM39$VXVNR#Or~==*K=}DVmmyS?cE?2+YNR1BQugRyMS0F-&~40s+$M zg@(KY#Ognup5HS5tCa!Z)#nmaOC9*}j=?EGbeyl=6g+1w^w4|mwOSHDS8rI95;++6 z#-$11Zgf=igu)?o6pZp&U=)lAqtio=an0hugO{?@+x$|N4cJ>(Wy&8!C|1+dk`tk* zMV$^i7T1vg!0=0}$sp#q#Wf`Wu>A5dE&|19Djg*XVuo8fUX>vj4cs9sAf=ex$v4TJ ze3R2B-{jQEH(5SUCQIkZB!8Yv7S5BEt#n(q(rwvFw-R=S;GrQ5QV zZcA3WowU;Jgq3cc9iDhHce1Zw-P?k7yThB`mGkwm*+?-KPIv+kwaH2k@_vssj`QU9 zEH%J_?OEV*$!jLsdJwX2zl!z4VIqZ{h z>U3Yemkv?k63;{vI8}kB4)Ow-6BI4k zVVpH%23MWXsxgbL&cwPgkFK0(1Q;`F~8fsN-#KbxZLVVR|kA$wk!CVDeo%Sz%O9egk^XcPM z1_qB)Lj$%U}L@UamerE}uRx z-!DHb@1OCw5zz~bPL$C%H2~jT*8r61!4uHK@JTBu44_a6970(|+#s4M3d1O=sGTlN zTPz87r~$R`VtIV2hzwhh>=BFx*8c=L5+~FJoi6c-W+z$L1I->c;A{jQIM`eS0V(`d zR0?Z_5N)FOEZj;X9=K^clsU)KjELgY#0^GIs@)YvoXCRQV)dCU!VYWBBNx7wMaLWd z>+gSWMte!&6A^QW(tOQaAnFxPLd;58pxUCQZ_OfWr59V*F`-kITTlT^cTx>q+dxC8 za*|C%kpR~PlSn2V5CP;E7YSETU>-X_BF|rJ+G;D=-Eu2sibh1NLAhMmnq^Y4>x}LL z*t@D*x5^nWCgU&{q!;#2l##=0kaIOiPDA0!E#znSZasS{!xmIQrP%^CF(*S-RwrDV zEU&egy9(+;39P&Z90q|j8wvs6P%duTZso>GzCuT7W_?8hj2ilH-M`}w3#lFvIaGEn z$nXiaJU-liC~zXi-T&8FHT$~aOfO2Aen%wk0$t8!?;@GZBn8-DrXn@a2|U_mV9HMAk4TE{^GDEb8=HdyI&MiG3VJ9fQhCCG+~xD6Jvf|s3VLrg{nV4# zwB9vJ4-zpg!sWtBS_LM=D(IO~k+O;K9c)b-!vpxfQ1v}q<8-Vaz9@wJ(ZqP{n%bqM zBd10$C#d?AQ`0iZ`@Asl&aW=c|CxPF2Pby8=O|wDRtvC&5z@SIH=z4Ck!Ynfa}eWk z=vb-~bM{Mw@t^^_C?41IakAaC?~nX45U0ZhRGSmmMNmWfk!*L(#!!6*5(f_cB8P`= zt)<9=sGTcEGQ1qS?LH>_Tx~zm`^5<+4h7`2p(4@_0BMc}~$~@I)ftrDqqW z>d4NfY0t(Egr`{N!Q&*0lL-zxFCJ$d7x3OW&KD>Q=Xe2)yju$Nq%JA=zG=4P*ae5y zb2DewGpC$cPp2GNuY-2AJTtmkt_$hgo6Wu%o3DcHMi7H{UrcWbfKT*(NrFN55Xvgd zC4^jo+btm%kua42*jb?$ehwTLeT=s-lmbOIWBY1X4ek+_pbSA~hSv};+h7^{y}v!4 z`YBFAZ1*~e+wS!^d@tYQ?8W?`uVeLfP#@~V9%f@34)w~yUK5;nt#|qw1p^M^$Z+SQ zmt|s(iu|^(xDPcVP;+Vo;`Cct#5VGMUw^qB1V;dX$of{Hq*@+tL=oBbBThf&u}(Pe zl=pN0sBaa_KJ4xBVVpR2vhELh4aLvX5JLsLfcz7eL?%H|XUY!Mx{&`fNNFaU{nN>? z&#H>;vc7(z-PRzd$;LZksor-Yh&Bly%M3aCD5}oQ#xq^!HrKEq;Vs#yAm^>~)y~RT~e4v-k4muD>XG%YrmeS-AD{|T|xN+H&xfGWk}V!Gy9a?Q?O7F z<=FV!Ol%1tW->*){IMME>3 zTAEGCA0R-ps9z@iE?%ys6#EzF+ozK#kY0YUqGVj94@|W{lc%c%7<}@2vG0ddp*F2NB|ZE8O>>@IpN5nh8zUeN za6x8*N)^0sx-S##2uZ0=$8J>9l z(DsldFAWx!_I%1pIAb-|01sr~&P-vfwroH!h>oY&1W%$DwMUj?Vwcu8%?~Cj8j7JV4~`{6XFGE7t86v`<=g8j*h0TooD787}Dv181S=1{eD@B zSU|wV*)Pr3-S|T(+S|(~p}wm5TE3P{fLQuWOTff}K@e}5bLE(L$7ZVZKhRrQ^;w^N z-^h`zS|CL5nN=AH|KBQ{F&q#di$?{UMd5j8uiqz^{kdiAb=#I#vezw{mSNqG*DasV z!HGk!tMqc=ZfYALMfsk?{!)Pw>!XFN9By@xg@wBv*L2EBNMf*CtEA&=r42m*fD@b5T`CpqozO4tSivVGDG~J{Q58-q$Yh0)UEOPbZ|NZa( zfqgNk($D!Z2Xw|{tnu2^-&U+25IPIv4N{$sGt+OF(apg-m`NYi>`Nt?>!h%91Bz3l z|J$vrp{ypLST!aS0y(87dIF47wCj(<&8coDzAM7`50m1y8RR(iWgf;UGCye0)MYgu zR8XQ^Ol9S(lN`l=*lp9B=2@k0Mhxd=7rBINu#kemDvJV20TT-EP&8ps>X| zob-Lk^Y}BK*$MCSUo+_f@s|HyvP!Ud6U zF|o2BS)ini*|t?g!K9A>9D1`$d~;FZ4rQ2PC0Hi`t~cE(rZDV-<82{Kne zJ+&38cW9dLW?ilP57l1=>Q@vQ6s&#%!oDF}{YiX$nN%0BlUk46kLU&HP-jWde_-p- z${24O4Q@c5``$>w-29hNXCb#H)cj+)B;gCVT$Qx;e!9fHFX7}VZo|!wasMCdhhoqf CHlN}E literal 0 HcmV?d00001 From 1e3674d700177b7f7846b3cc5d3053e2c20d7fc5 Mon Sep 17 00:00:00 2001 From: Brian Skinn Date: Tue, 10 Nov 2020 17:23:11 -0500 Subject: [PATCH 2/4] (ADMIN) Update changelog, clean up a test. --- CHANGELOG.md | 4 ++++ tests/test_api_good.py | 15 ++------------- 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7aeaccc..9788b583 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,10 @@ and this project strives to adhere to * Equality tests on Inventory and DataObjStr/DataObjBytes instances now work correctly. + * Non-integer and non-numeric values for `priority` are now accepted + during `Inventory` instantiation, consistent with what is allowed + by `DataObjStr` and `DataObjBytes` instantiation. + #### Refactored * Patterns in regular expressions are now defined with raw strings diff --git a/tests/test_api_good.py b/tests/test_api_good.py index ab93567e..a597455d 100644 --- a/tests/test_api_good.py +++ b/tests/test_api_good.py @@ -481,21 +481,10 @@ def test_api_inventory_datafile_gen_and_reimport( inv2 = soi.Inventory(str(scr_fpath)) # Test the things - with subtests.test(msg="content"): - assert inv1.project == inv2.project - assert inv1.version == inv2.version - assert inv1.count == inv2.count - for objs in zip(inv1.objects, inv2.objects): - assert objs[0].name == objs[1].name - assert objs[0].domain == objs[1].domain - assert objs[0].role == objs[1].role - assert objs[0].uri == objs[1].uri - assert objs[0].priority == objs[1].priority - assert objs[0].dispname == objs[1].dispname + assert inv1 == inv2 # Ensure sphinx likes the regenerated inventory - with subtests.test(msg="sphinx_load"): - sphinx_load_test(scr_fpath) + sphinx_load_test(scr_fpath) class TestWarnings: From 78dea4bf8b477b56fa2c118c079158f6bd45a609 Mon Sep 17 00:00:00 2001 From: Brian Skinn Date: Wed, 11 Nov 2020 15:40:50 -0500 Subject: [PATCH 3/4] Add non-numeric prio test; update syntax docs Much improved with the additional information about the constraints on the various fields, and I think much more readable with the line dividers. New inventory should test arbitrary `priority` content pretty well, though who knows if there are weird edge cases. Also fixed the make.bat `livehtml` invocation (was missing a '%' to close out %BUILDDIR%). --- doc/make.bat | 3 +- doc/source/syntax.rst | 90 ++++++++++++++++++++++++--- tests/resource/objects_prio_test.inv | Bin 0 -> 185 bytes 3 files changed, 84 insertions(+), 9 deletions(-) create mode 100644 tests/resource/objects_prio_test.inv diff --git a/doc/make.bat b/doc/make.bat index 613f65fc..b9c03e59 100644 --- a/doc/make.bat +++ b/doc/make.bat @@ -25,8 +25,9 @@ if errorlevel 9009 ( exit /b 1 ) + if "%1" == "livehtml" ( - sphinx-autobuild -b html %SOURCEDIR% %BUILDDIR/html %SPHINXOPTS% %O% %2 + sphinx-autobuild %SOURCEDIR% %BUILDDIR%/html -nb html %SPHINXOPTS% %O% %2 goto end ) diff --git a/doc/source/syntax.rst b/doc/source/syntax.rst index 9a859c86..45a502ca 100644 --- a/doc/source/syntax.rst +++ b/doc/source/syntax.rst @@ -11,6 +11,8 @@ Based upon a quick ``git diff`` of the `Sphinx repository `__, it is thought to be accurate for all Sphinx versions >=1.0b1 that make use of this "version 2" |objects.inv| format. +---- + **The first line** `must be exactly `__: @@ -18,6 +20,8 @@ Sphinx versions >=1.0b1 that make use of this "version 2" |objects.inv| format. # Sphinx inventory version 2 +---- + **The second and third lines** `must obey `__ the template: @@ -27,6 +31,8 @@ the template: # Project: # Version: +The version number should *not* include a leading "v". + .. _syntax-mouseover-example: The above project name and version are used to populate mouseovers for @@ -34,6 +40,8 @@ the |isphx| cross-references: .. image:: _static/mouseover_example.png +---- + **The fourth line** `must contain `__ the string 'zlib' somewhere in it, but for the purposes of consistency it should @@ -43,6 +51,7 @@ be exactly: # The remainder of this file is compressed using zlib. +---- **All remaining lines** of the file are the objects data, each laid out in the `following syntax @@ -54,35 +63,85 @@ be exactly: ``{name}`` The object name used when cross-referencing the object (falls between the - backticks) + backticks). + + **Constraints** + + * **MUST** have length greater than zero + + * **MUST NOT** contain whitespace ``{domain}`` The Sphinx domain used when cross-referencing the object (falls between - the first and second colons; omitted if using the |defdom|_) + the first and second colons; omitted if using the |defdom|_). + + **Constraints** + + * **MUST** have length greater than zero + + * **MUST** match a built-in or installable Sphinx domain + + * **MUST** consist of only |wordchars|_ + + * **RECOMMENDED** to consist of only ASCII word characters (``a-z``, ``A-Z``, + ``0-9``, and ``_``) ``{role}`` The Sphinx role used when cross-referencing the object (falls between the second and third colons; or, between the first and second colons if - using the |defdom|_) + using the |defdom|_). + + **Constraints** + + * **MUST** have length greater than zero + + * **MUST** match a role defined in the domain referenced by ``{domain}`` + + * **MUST** consist of only |wordchars|_ + + * **RECOMMENDED** to consist of only ASCII word characters (``a-z``, ``A-Z``, + ``0-9``, and ``_``) + ``{priority}`` Flag for `placement in search results `__. Most will be 1 (standard priority) or - -1 (omit from results) + __init__.py#L319-L325>`__. Most will be ``1`` (standard priority) or + ``-1`` (omit from results) for documentation built by Sphinx. + + To note, as of Nov 2020 this value is **not** used by ``intersphinx``; + it is only used internally within the search function of the static webpages + built *by Sphinx* (|prio_py_search|_ and |prio_js_search|_). Thus, custom + inventories likely **MAY** use this field for arbitrary content, if desired. + + **Constraints** + + * **MUST** have length greater than zero + + * **MUST NOT** contain whitespace ``{uri}`` Relative URI for the location to which cross-references will point. The base URI is taken from the relevant element of the |isphxmap| configuration parameter of ``conf.py``. + **Constraints** + + * **MUST** have length greater than zero + + * **MUST NOT** contain whitespace + ``{dispname}`` Default cross-reference text to be displayed in compiled documentation. -.. note:: + **Constraints** + + * **MUST** have length greater than zero - The above fields MUST NOT contain spaces, - except for ``{dispname}`` which MAY contain them. + * **MAY** contain internal whitespace (leading/trailing whitespace + is ignored) + +---- **For illustration**, the following is the entry for the :meth:`join() ` method of the :class:`str` class in the @@ -129,6 +188,8 @@ The cross-reference would show as :meth:`str.join` and link to the relative URI: library/stdtypes.html#str.join +---- + **Other intersphinx Syntax Examples** To show as only :meth:`~str.join`: @@ -152,7 +213,20 @@ as in :obj:`This is join! `: +.. ## Definitions ## + .. |defdom| replace:: default domain .. _defdom: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html +.. |wordchars| replace:: word characters + +.. _wordchars: https://docs.python.org/3.8/library/re.html#index-32 + +.. |prio_js_search| replace:: here + +.. _prio_js_search: https://github.com/sphinx-doc/sphinx/blob/d17563987a80007e2310102cfde673c651823a39/sphinx/themes/basic/static/searchtools.js#L26-L43 + +.. |prio_py_search| replace:: here + +.. _prio_py_search: https://github.com/sphinx-doc/sphinx/blob/624f6937194e1acfe7311faf6e27e370c3118e55/sphinx/search/__init__.py#L332 diff --git a/tests/resource/objects_prio_test.inv b/tests/resource/objects_prio_test.inv new file mode 100644 index 0000000000000000000000000000000000000000..36007e552f6686c717eaeecbe7548f990970deb3 GIT binary patch literal 185 zcmY#Z2rkIT%&Sny%qvUHE6FdaR47X=D$dN$Q!wIERtPA{&q_@$u~P8M&r1dJ!ys~S zen>{DLQ!gNVrE`SYLP;InnFoNX0bwAW=^UCkWS9eEhtJYE>2BRC@s#+OIN7M$xPDY zs<`ES`h2*?iY;EAI-Vg0ApwCGo_cxdGg%t&PP1>|+DPsgH1FyN{D*#XCN8A7a literal 0 HcmV?d00001 From 6ed949fe5f128190a5039044ffdbe5efd4117ce1 Mon Sep 17 00:00:00 2001 From: Brian Skinn Date: Fri, 13 Nov 2020 06:19:18 -0500 Subject: [PATCH 4/4] Add note about custom prio possibly breaking later In the case that Sphinx/intersphinx *were* to impose some constraints on the field. --- doc/source/syntax.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/syntax.rst b/doc/source/syntax.rst index 45a502ca..b913bbe5 100644 --- a/doc/source/syntax.rst +++ b/doc/source/syntax.rst @@ -113,6 +113,8 @@ be exactly: it is only used internally within the search function of the static webpages built *by Sphinx* (|prio_py_search|_ and |prio_js_search|_). Thus, custom inventories likely **MAY** use this field for arbitrary content, if desired. + This *would* run the risk of a future change to Sphinx/intersphinx causing + such custom |objects.inv| files to become incompatible. **Constraints**