SrSSKrSSKrSSKrSSKrSSKrSSKrSSKrSSKrSSK r SSK r SSK r SSK r SSKr SSKr SSKr SSKJr /SQrSrSrSr\R0"S\<S \<S 35rS \-r\R0"S \<\<S 35rSr/0\"54rSrSr Sr!Sr"\ RFRHRKSS5r&\ RFRHRKSSS5r'\ RFRHRKSSS5r("SS\)5r*Sr+\ RFRHRYS\*"SSS S!S"54S#\*"S$S%S$S&S'54S(\*"S)S*S)S+S,54S-\*"S.S.S/S0S154S2\*"S3S3S4S5\+545r-"S6S7\R\"S7/S8Q55r/"S9S:\R\"S:/S;Q55r0SS<\(RbS4S=jr2S>r3S?r4S@r5SAr6S_SBjr7SCr8SDr9S`SEjr:SFr;SGrSJr?SKr@S`SLjrASbSMjrBSNrCSOrD"SPSQ\)5rE"SRSS\)5rFScSTjrGSUrHSVrIS`SWjrJSXrKSYrLSZrMS[rNS\rOS`S]jrPSdS^jrQSSKRr SSKSr SSKTr SSKUr SSKVr SSKWr SSKXr g!\a SSKJr GN=f=f)ea Package for parsing and processing descriptor data. **Module Overview:** :: parse_file - Parses the descriptors in a file. create_signing_key - Cretes a signing key that can be used for creating descriptors. Compression - method of descriptor decompression Descriptor - Common parent for all descriptor file types. | |- content - creates the text of a new descriptor | |- create - creates a new descriptor | +- from_str - provides a parsed descriptor for the given string | |- type_annotation - provides our @type annotation |- get_path - location of the descriptor on disk if it came from a file |- get_archive_path - location of the descriptor within the archive it came from |- get_bytes - similar to str(), but provides our original bytes content |- get_unrecognized_lines - unparsed descriptor content +- __str__ - string that the descriptor was made from .. data:: DigestHash (enum) .. versionadded:: 1.8.0 Hash function used by tor for descriptor digests. =========== =========== DigestHash Description =========== =========== SHA1 SHA1 hash SHA256 SHA256 hash =========== =========== .. data:: DigestEncoding (enum) .. versionadded:: 1.8.0 Encoding of descriptor digests. ================= =========== DigestEncoding Description ================= =========== RAW hash object HEX uppercase hexidecimal encoding BASE64 base64 encoding `without trailing '=' padding `_ ================= =========== .. data:: DocumentHandler (enum) Ways in which we can parse a :class:`~stem.descriptor.networkstatus.NetworkStatusDocument`. Both **ENTRIES** and **BARE_DOCUMENT** have a 'thin' document, which doesn't have a populated **routers** attribute. This allows for lower memory usage and upfront runtime. However, if read time and memory aren't a concern then **DOCUMENT** can provide you with a fully populated document. Handlers don't change the fact that most methods that provide descriptors return an iterator. In the case of **DOCUMENT** and **BARE_DOCUMENT** that iterator would have just a single item - the document itself. Simple way to handle this is to call **next()** to get the iterator's one and only value... :: import stem.descriptor.remote from stem.descriptor import DocumentHandler consensus = next(stem.descriptor.remote.get_consensus( document_handler = DocumentHandler.BARE_DOCUMENT, ) =================== =========== DocumentHandler Description =================== =========== **ENTRIES** Iterates over the contained :class:`~stem.descriptor.router_status_entry.RouterStatusEntry`. Each has a reference to the bare document it came from (through its **document** attribute). **DOCUMENT** :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` with the :class:`~stem.descriptor.router_status_entry.RouterStatusEntry` it contains (through its **routers** attribute). **BARE_DOCUMENT** :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` **without** a reference to its contents (the :class:`~stem.descriptor.router_status_entry.RouterStatusEntry` are unread). =================== =========== N) OrderedDict)bandwidth_file certificate collectorexportextrainfo_descriptorhidden_servicemicrodescriptor networkstatusreaderremoterouter_status_entryserver_descriptortordnsel Descriptor parse_filezFile object isn't seekable. Try using Descriptor.from_str() instead: content = my_file.read() parsed_descriptors = stem.descriptor.Descriptor.from_str(content) z a-zA-Z0-9-z z^([z]+)(?:[ ]+(.*))?$z^(%%s)(?:[%s]+(.*))?$z^-----BEGIN ([z ]+)-----$z-----END %s-----sz MIGJAoGBAJv5IIWQ+WDWYUdyA/0L8qbIkEVH/cwryZWoIaPAzINfrw1WfNZGtBmg skFtXhOHHqTRN4GPPrZsAIUOQGzQtGb66IQgT4tO/pj+P6QmSCCdTfhvGfgTCsC+ WPi4Fl2qryzTb3QO5r5x7T8OsG2IBUET1bLQzmtbC560SYR49IvVAgMBAAE= SHA1SHA256RAWHEXBASE64ENTRIESDOCUMENT BARE_DOCUMENTc*\rSrSrSrSrSrSrSrg) _Compressiona\ Compression method supported by CollecTor. :var bool available: **True** if this method of decryption is available, **False** otherwise :var str encoding: `http 'Accept-Encoding' parameter `_ :var str extension: file extension of this compression .. versionadded:: 1.8.0 cUcSUlSUlO[U5UlSUlX@lX0lXlX lXPlg![a SUlSUlN9f=fNTF) _module available __import__ ImportError extensionencoding_name _module_name_decompression_func)selfnamemoduler(r'decompression_funcs R/home/james-whalen/.local/lib/python3.13/site-packages/stem/descriptor/__init__.py__init___Compression.__init__si ~dldn !&)  NMJ1 sA A%$A%cDUR(dNURS:Xa [S5eURS:Xa [S5e[SUR-5eUR UR U5$![ an[SU<SU<35eSnAff=f) aC Decompresses the given content via this method. :param bytes content: content to be decompressed :returns: **bytes** with the decompressed content :raises: If unable to decompress this provide... * **IOError** if content isn't compressed with this * **ImportError** if this method if decompression is unavalable zstdzDDecompressing zstd data requires https://pypi.org/project/zstandard/lzmazLDecompressing lzma data requires https://docs.python.org/3/library/lzma.htmlz('%s' decompression module is unavailablezFailed to decompress as z: N)r$r)r&r*r+r# ExceptionIOError)r,contentexcs r0 decompress_Compression.decompresss >> v `aa :: hiiDtGXGXXYYD  % %dllG << D cB CCDs!A== BBBcUR$N)r)r,s r0__str___Compression.__str__s ::)r+r#r*r)r$r(r'N) __name__ __module__ __qualname____firstlineno____doc__r1r:r?__static_attributes__rAr0rrs 2.D8rArc[R"5nUR5RU5nUR U5 SSS5 UR 5$!,(df  UR 5$=fr=)ioBytesIOZstdDecompressorwrite_towritegetvalue)r.r8 output_buffer decompressors r0_zstd_decompressrRsd**,-  ))-8Lw9    !!98    !!s A A< PLAINTEXT plaintextidentityz.txtcU$r=rHr.r8s r0rXs\crAGZIPgzipzlibz.gzc>URXRS-5$)N )r: MAX_WBITSrWs r0rXrXs vO`O`ahjzjz}jPArABZ2bzip2bz2z.bz2c$URU5$r=r:rWs r0rXrXsPVPaPabiPjrALZMAr5z x-tor-lzmaz.xzc$URU5$r=rcrWs r0rXrXsU[UfUfgnUorAZSTDr4zx-zstdz.zstc\rSrSrSrSrSrg)TypeAnnotationiaa `Tor metrics type annotation `_. The string representation is the header annotation, for example "@type server-descriptor 1.0". .. versionadded:: 1.8.0 :var str name: name of the descriptor type :var int major_version: major version number :var int minor_version: minor version number cZSUR<SUR<SUR<3$)Nz@type  .r- major_version minor_versionr>s r0r?TypeAnnotation.__str__s#yy$*<*P>P QQrArHN)rBrCrDrErFr?rGrHrAr0rhrhs  RrArhrlc\rSrSrSrSrg) SigningKeyiaa Key used by relays to sign their server and extrainfo descriptors. .. versionadded:: 1.6.0 :var cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey private: private key :var cryptography.hazmat.backends.openssl.rsa._RSAPublicKey public: public key :var bytes public_digest: block that can be used for the a server descrptor's 'signing-key' field rHN)rBrCrDrErFrGrHrAr0rqrqsrArq)privatepublic public_digestFc+^^^^^^ ^ ^ # Sn[RRU5(a<[RRR U5(a[ nO,[ nO%[U[R5(a[nU(aU"UTTT40TD6HnUv M gUR5 UR5n[RRRUR!5R#55m [$R&"ST 5m T (dUR)U5 [+USS5n U cSO([,R.R1UR25m UUU U UU UU4Sjn U "U5H8nU b.UR5[,R.R7U 55 Uv M: g![a [[5ef=f7f)a: Simple function to read the descriptor contents from a file, providing an iterator for its :class:`~stem.descriptor.__init__.Descriptor` contents. If you don't provide a **descriptor_type** argument then this automatically tries to determine the descriptor type based on the following... * The @type annotation on the first line. These are generally only found in the `CollecTor archives `_. * The filename if it matches something from tor's data directory. For instance, tor's 'cached-descriptors' contains server descriptors. This is a handy function for simple usage, but if you're reading multiple descriptor files you might want to consider the :class:`~stem.descriptor.reader.DescriptorReader`. Descriptor types include the following, including further minor versions (ie. if we support 1.1 then we also support everything from 1.0 and most things from 1.2, but not 2.0)... ========================================= ===== Descriptor Type Class ========================================= ===== server-descriptor 1.0 :class:`~stem.descriptor.server_descriptor.RelayDescriptor` extra-info 1.0 :class:`~stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor` microdescriptor 1.0 :class:`~stem.descriptor.microdescriptor.Microdescriptor` directory 1.0 **unsupported** network-status-2 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV2`) dir-key-certificate-3 1.0 :class:`~stem.descriptor.networkstatus.KeyCertificate` network-status-consensus-3 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) network-status-vote-3 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) network-status-microdesc-consensus-3 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) bridge-network-status 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.BridgeNetworkStatusDocument`) bridge-server-descriptor 1.0 :class:`~stem.descriptor.server_descriptor.BridgeDescriptor` bridge-extra-info 1.1 or 1.2 :class:`~stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor` torperf 1.0 **unsupported** bridge-pool-assignment 1.0 **unsupported** tordnsel 1.0 :class:`~stem.descriptor.tordnsel.TorDNSEL` hidden-service-descriptor 1.0 :class:`~stem.descriptor.hidden_service.HiddenServiceDescriptorV2` ========================================= ===== If you're using **python 3** then beware that the open() function defaults to using text mode. **Binary mode** is strongly suggested because it's both faster (by my testing by about 33x) and doesn't do universal newline translation which can make us misparse the document. :: my_descriptor_file = open(descriptor_path, 'rb') :param str,file,tarfile descriptor_file: path or opened file with the descriptor contents :param str descriptor_type: `descriptor type `_, this is guessed if not provided :param bool validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise :param stem.descriptor.__init__.DocumentHandler document_handler: method in which to parse the :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` :param bool normalize_newlines: converts windows newlines (CRLF), this is the default when reading data directories on windows :param dict kwargs: additional arguments for the descriptor constructor :returns: iterator for :class:`~stem.descriptor.__init__.Descriptor` instances in the file :raises: * **ValueError** if the contents is malformed and validate is True * **TypeError** if we can't match the contents of the file to a descriptor type * **IOError** if unable to read from the descriptor_file Nz^@type (\S+) (\d+).(\d+)$r-z c,>T (a [U5nTb_[R"ST5nU(a6UR5up#n[ U[ U5[ U5UT T40T D6$[ S5eT (a6T R5up#n[ U[ U5[ U5UT T40T D6$T c8[RRR5(a [U5nTS:XdTS:Xa-[RRR"U4ST 0T D6$TS:XdTS:Xa-[RRR"U4ST 0T D6$TS:XdTS :Xa-[RRR"U4ST 0T D6$TS :Xa.[RR R"U4T TS .T D6$TS :Xa/[RR R"U4S T TS.T D6$[#ST<ST<S35e)Nz^(\S+) (\d+).(\d+)$zPThe descriptor_type must be of the form ' .'zcached-descriptorszcached-descriptors.newvalidatezcached-extrainfozcached-extrainfo.newzcached-microdescszcached-microdescs.newzcached-consensusrwdocument_handlerzcached-microdesc-consensusTis_microdescriptorrwryz6Unable to determine the descriptor's type. filename: 'z', first line: '')NewlineNormalizerrematchgroups_parse_metrics_fileint ValueErrorstemutilsystem is_windows descriptorr _parse_filerr r TypeError) descriptor_filedescriptor_type_match desc_typermrndescriptor_typeryfilename first_linekwargsmetrics_header_matchnormalize_newlinesrws r0parseparse_file..parsesF)/:o" hh'?Q 2G2N2N2P/ -"9c-.@#mBTVegorBMFLM Mkll 1E0K0K0M-i C ,>M@RTcemoKDJKK  # (8(8(C(C(E(E+O< ) )X9Q-Q00<<_lYalekll ) )X9O-O33??o\dohnoo * *h:Q.Q..::?jW_jcijj ) ),,88NU]sCNGMN N 3 3,,88i_cpxN^ibhi iiqs}~rA)rr_is_strr is_tarfile_parse_file_for_tar_path_parse_file_for_path isinstancetarfileTarFile_parse_file_for_tarfiletellr7UNSEEKABLE_MSG str_tools _to_unicodereadlinestripr~rseekgetattrospathbasenamer- _set_pathabspath)rrrwryrrhandlerdescinitial_positiondescriptor_pathrrrrs ````` @@@r0rr$sP ' YY'' yy""?33(g$g/7??33%G (DT_X^_ j` "%))+yy""../G/G/I/O/O/QR*"@*M )*OVT:/-5]277;K;KOL`L`;a("@"@HO$d" nnRWW___56 J %o " . !!"sB'G02GDG0G--G0c/# [US5n[U/UQ70UD6HnUv M SSS5 g!,(df  g=f7f)Nrb)openr)rargsr desc_filers r0rrs: OT"i96t6v6 j7#""s A3 A AAc/4# [R"U5n[U/UQ70UD6H5nUR[R R U55 Uv M7 U(aUR5 gg!U(aUR5 ff=f7fr=)rrrrrrrclose)rrrtar_filers r0rrsu \\/ *(85d5f5 nnRWW___56 j6nnxnnsBAA;"B;BBc/H# UHnUR5(dMURU5nURS:XaM=[U/UQ70UD6H"nUR UR 5 Uv M$ UR 5 M g!UR 5 f=f7fNr)isfile extractfilesizer_set_archive_pathr-r)rrr tar_entryentryrs r0rrs"i)))4e 1 u6t6v6D   ,*7  #  s"B"#B"5B 8B" BB"c+# U[RRRR:Xa@US:Xa:[RRR "U4SUS.UD6HnUv M gU[RRR R:Xa@US:Xa:[RRR "U4SUS.UD6HnUv M gU[RRRR:Xa@US:Xa:[RRR "U4SUS.UD6HnUv M gU[RRRR:Xa?US:Xa9[RRR "U4SU0UD6HnUv M gU[RRRR:Xa@US:Xa:[RRR "U4SUS.UD6HnUv M gU[RRRR:XacUS:Xa][RRRn[RRR "X84XES.UD6HnUv M gU[RRRR:Xa?US:Xa9[RRR"U4SU0UD6HnUv M gUS;acUS:Xa][RRR n[RRR "X84XES.UD6HnUv M gUS:XadUS:Xa^[RRR n[RRR "X84SXES .UD6HnUv M gU[RRR"R:XacUS:Xa][RRR"n[RRR "X84XES.UD6HnUv M gU[RRR$R:XacUS:Xa][RRR$n[RRR "X84XES.UD6HnUv M gU[RR&R(R:Xa?US:Xa9[RR&R "U4SU0UD6HnUv M gU[RR*R,R:XacUS:Xa][RR*R,n [RR*R "X94SU0UD6HnUv M gU[RR*R.R:XacUS:Xa][RR*R.n [RR*R "X94SU0UD6HnUv M gU[RR0R2R:Xa?US:Xa9[RR0R "U4SU0UD6HnUv M g[5S XU4-5e7f) NF) is_bridgerwTrwrx)znetwork-status-consensus-3znetwork-status-vote-3z$network-status-microdesc-consensus-3rzzDUnrecognized metrics descriptor format. type: '%s', version: '%i.%i')rrrRelayDescriptorTYPE_ANNOTATION_NAMErBridgeDescriptorrRelayExtraInfoDescriptorr MicrodescriptorBridgeExtraInfoDescriptorr NetworkStatusDocumentV2KeyCertificate_parse_file_key_certsNetworkStatusDocumentV3BridgeNetworkStatusDocumentDetachedSignaturerTorDNSELr HiddenServiceDescriptorV2HiddenServiceDescriptorV3r BandwidthFiler) rrmrnrrwryrr document_typers r0rrsK99II^^^cptucu11==oA[`muAyA jA$//;;LLaaafswxfx11==o[_ltx~ j@$//>>WWlllq~CDrD44@@D^cpxD}CD jD$//99II^^^cptucu//;;OkX`kdjk jl$//>>XXmmmrDEsE44@@C^bowC|BC jC$//77OOdddivz{i{OO11IIM--99/^em^W]^ j^$//77FF[[[`mqr`r--CCOs`hslrs jtQQVcghVhOO11IIM--99/^em^W]^ j^@@]VWEWOO11IIM--99/yosAIyrxy jy$//77SShhhmz~mOO11MMM--99/^em^W]^ j^$//77II^^^cptucuOO11CCM--99/^em^W]^ j^$//22;;PPPUbfgUg((44_dQYd]cd je$//88RRgggly}~l~..HHI..::?ubjuntu jv$//88RRgggly}~l~..HHI..::?ubjuntu jv$//88FF[[[`mqr`r..::?jW_jcij jk Z^mL^MM NNs]]cz//pTUc0O [U5nXB4XS44HupgUHupX;aM [RRR UR X55n U cMI[ U [[45(a#U Hn URU<SU <35 M MU S:XaURU5 MU RS5(aURU<U <35 MURU<SU <35 M M /n UR5HUup[ U [[45(aXV s/sH o<SU <3PM sn - n M=U RU <SU <35 MW [RRRSRXK-U-55$s sn f)a Constructs a minimal descriptor with the given attributes. The content we provide back is of the form... * header_template (with matching attr filled in) * unused attr entries * footer_template (with matching attr filled in) So for instance... :: _descriptor_content( attr = {'nickname': 'caerSidi', 'contact': 'atagar'}, header_template = ( ('nickname', 'foobar'), ('fingerprint', '12345'), ), ) ... would result in... :: nickname caerSidi fingerprint 12345 contact atagar :param dict attr: keyword/value mappings to be included in the descriptor :param list exclude: mandatory keywords to exclude from the descriptor :param tuple header_template: key/value pairs for mandatory fields before unrecognized content :param tuple footer_template: key/value pairs for mandatory fields after unrecognized content :returns: bytes with the requested descriptor content rj )rrrrrpoprtuplelistappend startswithitems _to_bytesjoin)attrexcludeheader_templatefooter_templateheader_contentfooter_contentr8templatekeywordvaluev remainderkrs r0_descriptor_contentr*swJ$&r.|T!2$+=+=?g"  ii!!--dhhw.FGe  eeT] + +A ..GQ/ 0 B;w   D ! !%01'512##?*)jjlda!eT]##a8aUq%(a88i!Q'(     & &tyy1Kn1\'] ^^ 9sF8cXSS$rrH)lineentriess r0_valuerrs q ! rAc:XVs/sHo"SPM sn$s snfrrH)rrrs r0_valuesrvs ' . u( .. .sc^^^UUU4SjnU$)Nc`>[TU5n[UTT(a T"U55 gU5 gr=)rsetattr)rrr attributefuncrs r0_parse"_parse_simple_line.._parse{s& 7G $E J $4;BEBrArH)rrrrs``` r0_parse_simple_linerzsC -rAc^^UU4Sj$)Nc$>[UTTU;5$r=)r)rrrrs r0rX#_parse_if_present..sWZGwDV%WrArH)rrs``r0_parse_if_presentrs WWrAc^^UU4SjnU$)Nc 6>[R"[RRR ST<S[ <S35UR5[R5nSnU(aUR5SnUcSOUn[UTU5 g)Nz^(opt )?z(?:[rrrA) r~searchrrrr WHITESPACE get_bytes MULTILINErr)rr line_matchresultrrrs r0r!_parse_bytes_line.._parses499..88X_ak9lmoypDpDpFHJHTHTUJ F!!$emsf J 6*rArHrrrs`` r0_parse_bytes_liners+ -rAc^^^UUU4SjnU$)Nc>[TU5n[U5nT(dUS:a[T<SU<35e[UTU5 g![a [T<SU<35ef=f)Nz must have a numeric value: rz must have a positive value: )rrrr)rrrint_valallow_negativerrs r0r_parse_int_line.._parsesh 7G $ENE g gk guM NN J 7+ N WeL MMNs AA$rH)rrr rs``` r0_parse_int_liner s , -rAc^^UU4SjnU$)Nc >[TU5n[UT[RRR U55 g![ a [ ST<ST<SU<35ef=f)Nz Timestamp on z line wasn't parsable: rj)rrrrr_parse_timestamprrrrrrs r0r%_parse_timestamp_line.._parses[ 7G $Eb j)TYY%8%8%I%I%%PQ b QXZ_` aabs 4A"A&rHrs`` r0_parse_timestamp_linersb -rAc^^UU4SjnU$)Nc>[TU5n[RRR US5(d[ T<ST<SU<35e[ UTU5 g)N(z: line had an invalid value (should be 40 hex characters): rj)rrr tor_tools is_hex_digitsrrrs r0r*_parse_forty_character_hex.._parsesM 7G $E 99   , ,UB 7 7 ^egnpuv ww J 5)rArHrs`` r0_parse_forty_character_hexrs* -rAc^^UU4SjnU$)Nc >[T U5n[5n[T U5HupE/nU(dMURS5HnSU;aURSS5upOU=pUR 5(aU R 5(d[ ST <SU<35eU[ [U5[U 5S-5- nM XcU'M [UT U5 g)N,-rz=Protocol values should be a number or number range, but was: rj) rr _mappings_forsplitisdigitrrangerr) rrr protocolsrrversionsr min_value max_valuerrs r0r$_parse_protocol_line.._parses 7G $E Igu-h 773<% %UTSup#nU(aUT:wa[ST<ST<SU<35e[UTU5 T(a[UTU5 gg)Nrr|z' should be followed by a z block, but was a )rr) rrr block_typeblock_contentsrexpected_block_typervalue_attributes r0r _parse_key_block.._parsesW(/(8(;%E~ Z+>> PWYlnxy zz J >2 j/51rArH)rrr-r.rs```` r0_parse_key_blockr0s 2 2 -rAc ## UcgUS:XagURU5HZnSU;a[SU<SU<35eURSS5upVU(aU(d[SU<SU<SU<35eXV4v M\ g7f) aE Parses an attribute as a series of 'key=value' mappings. Unlike _parse_* functions this is a helper, returning the attribute value rather than setting a descriptor field. This way parsers can perform additional validations. :param str keyword: descriptor field being parsed :param str value: 'attribute => values' mappings to parse :param str divider: separator between the key/value mappings :param bool require_value: validates that values are not empty :returns: **generator** with the key/value of the map attribute :raises: **ValueError** if descriptor content is invalid Nr=r|z3' should be a series of 'key=value' pairs but was: rz ' line's z mapping had a blank value: )r r)rr require_valuedividerrrrs r0rrsx  ]  { {{7#e % U\^cd ee ;;sA DAQ RSUZ[ \\ $J$sAcUb/[U[[RR45(aU$U[ ;a[ U5"5$[R"U5$r=)rboolr exit_policy ExitPolicyEMPTY_COLLECTIONtypecopy)defaults r0_copyr=sM _ 7T43C3C3N3N,OPP N"" =? 99W rAc8U[R:XaU$U[R:XaE[RR R UR5R55$U[R:XaZ[RR R [R"UR55RS55$U[;a&[SSR[5<SU<35e[!SU-5e)z3 Encodes a hash value with the given HashEncoding. =zADigest encodings should be among our DigestEncoding enumeration (z, z), not zRBUG: stem.descriptor._encode_digest should recognize all DigestEncoding, lacked %s)DigestEncodingrrrrrr hexdigestupperrbase64 b64encodedigestrstriprrNotImplementedError) hash_valuer(s r0_encode_digestrIs ### >%%% 99   * *:+?+?+A+G+G+I JJ>((( 99   * *6+;+;JThe create and content methods haven't been implemented for %s)rGrB)r[rrsigns r0r8Descriptor.contentms. ^adamamm nnrAc0U"URXU5US9$)aJ Creates a descriptor with the given attributes. Mandatory fields are filled with dummy information unless data is supplied. This doesn't yet create a valid signature. .. versionadded:: 1.6.0 :param dict attr: keyword/value mappings to be included in the descriptor :param list exclude: mandatory keywords to exclude from the descriptor, this results in an invalid descriptor :param bool validate: checks the validity of the descriptor's content if **True**, skips these checks otherwise :param bool sign: includes cryptographic signatures and digests if True :returns: :class:`~stem.descriptor.Descriptor` subclass :raises: * **ValueError** if the contents is malformed and validate is True * **ImportError** if cryptography is unavailable and sign is True * **NotImplementedError** if not implemented for this descriptor type )rwr8)r[rrrwras r0createDescriptor.creates0 s{{4$/H EErAcURb[URSS5$[S[U5R-5e)a Provides the `Tor metrics annotation `_ of this descriptor type. For example, "@type server-descriptor 1.0" for server descriptors. Please note that the version number component is specific to CollecTor, and for the moment hardcode as 1.0. This may change in the future. .. versionadded:: 1.8.0 :returns: :class:`~stem.descriptor.TypeAnnotation` with our type information rrz#%s does not have a @type annotation)rrhrGr:rBr>s r0type_annotationDescriptor.type_annotations@"   , D55q! <<  ET H[H[ [ \\rAcUR$)z Provides the absolute path that we loaded this descriptor from. :returns: **str** with the absolute path of the descriptor source rLr>s r0get_pathDescriptor.get_paths ::rAcUR$)a7 If this descriptor came from an archive then provides its path within the archive. This is only set if the descriptor came from a :class:`~stem.descriptor.reader.DescriptorReader`, and is **None** if this descriptor didn't come from an archive. :returns: **str** with the descriptor's path within the archive rMr>s r0get_archive_pathDescriptor.get_archive_paths   rAch[RRRUR5$)z Provides the ASCII **bytes** of the descriptor. This only differs from **str()** if you're running python 3.x, in which case **str()** provides a **unicode** string. :returns: **bytes** for the descriptor's contents )rrrrrNr>s r0rDescriptor.get_bytess% 99   ( ();); <s r0get_unrecognized_lines!Descriptor.get_unrecognized_liness8  kk$--' d (( ))rAc:Uc URn[UR55HVupEXC;a X4"X5 MUH9upgnU<SU<3n U(aU SU-- n URR U 5 M; MX g![ a U(aeMpf=f)a\ Parses a series of 'keyword => (value, pgp block)' mappings and applies them as attributes. :param dict entries: descriptor contents to be applied :param bool validate: checks the validity of descriptor content if True :param dict parsers: mapping of lines to the function for parsing it :raises: **ValueError** if an error occurs in validation Nrjz %s)PARSER_FOR_LINErrrRrr) r,rrwparser_for_linervaluesrr+r,rs r0rDescriptor._parses,,o 0   %  "4 139/e%u-Df~--d  $ $ + +D 1 4: 1   sB?BBBcXlgr=rkr,rs r0rDescriptor._set_pathsJrAcXlgr=ror}s r0rDescriptor._set_archive_pathsrAc*[[U55$r=)rYr:)r, is_plurals r0r)Descriptor._name s tDz?rAc[RR5(d [S5eSSKJn SSKJn SSKJ n U"[U5U"55nUR5RnUR5Rn[U5n [RU SS9n [!U 5n [#XU5n U"X5n U R%[&5S:wa [S5eS nU R%[(U5n[*R,"XS -S S5n[R.R0R3UR555$![a [S 5ef=f![a [S 5ef=f)a@ Provides the signed digest we should have given this key and signature. :param str signing_key: key block used to make this signature :param str signature: signed digest for this descriptor content :returns: the digest string encoded in uppercase hex :raises: ValueError if unable to provide a validly signed digest z=Generating the signed digest requires the cryptography modulerdefault_backend)load_der_public_key) int_to_bytesbig) byteorderz'Verification failed, identifier missingz#Verification failed, malformed dataz(Verification failed, seperator not foundrN hex_codec)rprereqis_crypto_availablercryptography.hazmat.backendsr,cryptography.hazmat.primitives.serializationrcryptography.utilsr_bytes_for_blockpublic_numbersner from_bytesrZpowindexDIGEST_TYPE_INFODIGEST_SEPARATORcodecsencoderrrrB)r, signing_key signaturerrrkeymoduluspublic_exponent sig_as_bytes sig_as_long blocksize decrypted_intdecrypted_bytesidentifier_offsetseperator_index digest_hexs r0_digest_for_signature Descriptor._digest_for_signaturesq ;; * * , , V WW<P/ .{;_=N OC  "$$G((*,,O#I.L...?KL!I g>M#=   / 0A 5BCC 6 C(--.>@QRo/B/CDkRJ 99   * *:+;+;+= >> > < ==> C A BBCs $E1E5E25F cUR5nSupEUbLUR[RRR U55nUS:Xa[ SU-5eUb[UR[RRR U5U5nUS:Xa[ SU-5eU[U5- nX4U$)a Provides the descriptor content inclusively between two substrings. :param bytes start: start of the content range to get :param bytes end: end of the content range to get :raises: ValueError if either the start or end substring are not within our content NNz1'%s' is not present within our descriptor content)rfindrrrrrrZ)r,startendr8 start_index end_indexs r0_content_rangeDescriptor._content_rangeLsnnG'K LL!4!4!>!>u!EFk  LuTUU ,,tyy22<^UU4SjnUTR;aZU"U5(dMTRUup4TR(aU"TTR5 O[ TU[U55 [[T]+U5$![[4aU TRR 5H4unupgXG:XdMU"U5(aM[ TU[U55 M6 Nwf=f)Nc<>[[T] U5 g! g=fr")superr__getattribute__)r __class__r,s r0has_attr(Descriptor.__getattr__..has_attrns$ j$06s) ATTRIBUTESrOrPrKeyErrorrrr=rrr) r,r-rr<parsing_function attr_name attr_default attr_parserrs ` r0 __getattr__Descriptor.__getattr__is  tx~~"&//$"7g   < 4 / dE'N+ T 3D 99H% < 9=8M8M8O4i4,.x 7J7JdIu\':;9P  s r0r?Descriptor.__str__sB {{  YY , ,T-?-? @@   rAc[U5[U5:wagU"[U5R5[U5R55$)NF)r:rYr)r,othermethods r0_compareDescriptor._compares: DzT%[  #d)//#SZ%5%5%7 88rAcURc'[[U5R55UlUR$r=)rQhashrYrr>s r0__hash__Descriptor.__hash__s- zzD )*dj ::rAc(URUS5$)Nc X:H$r=rHsos r0rX#Descriptor.__eq__..QVrArr,rs r0__eq__Descriptor.__eq__ == 3 44rAc X:X+$r=rHrs r0__ne__Descriptor.__ne__s  rAc(URUS5$)Nc X:$r=rHrs r0rX#Descriptor.__lt__..sQUrArrs r0__lt__Descriptor.__lt__s == 2 33rAc(URUS5$)Nc X:*$r=rHrs r0rX#Descriptor.__le__..rrArrs r0__le__Descriptor.__le__rrA)rMrPrQrOrLrNrR)F)NrHF)NrHTFr=r)"rBrCrDrErFrrxrr1 classmethodr^r8rerhrlrprrurrrr)rrrr?rrrrrrrG __classcell__)rs@r0rr*s*/".y.y`oo0FF2],  =* ><?|*:":H 9  5455rArc<\rSrSrSrSrSrSrSrSr Sr S r g ) r}iz1 File wrapper that normalizes CRLF line endings. c4Xl[USS5Ulg)Nr-) _wrapped_filerr-)r, wrapped_files r0r1NewlineNormalizer.__init__s% fd3DIrAcTURR"U6RSS5$Ns  )rreadreplacer,rs r0rNewlineNormalizer.reads&    " "D ) 1 1'5 AArAcTURR"U6RSS5$r)rrrrs r0rNewlineNormalizer.readlines&    & & - 5 5gu EErAc|URR"U6Vs/sHo"RS5PM sn$s snf)N )r readlinesrF)r,rrs r0rNewlineNormalizer.readliness4+/+=+=+G+G+N O+N4KK +N OO Os9c4URR"U6$r=)rrrs r0rNewlineNormalizer.seek    " "D ))rAc4URR"U6$r=)rrrs r0rNewlineNormalizer.tellrrA)rr-N) rBrCrDrErFr1rrrrrrGrHrAr0r}r}s(4BFP**rAr}cU(aSO/nSn[RRU5(aU4nU(a+UR5n U (aUbUR U 5 [ R "[SRU5-5n UR5n U(aX:aOUR5n U (dOU R[RRRU 55n U (aAU R5SnU(dURU 5 OUbUR U 5 OUbUR U 5 MU(aXx4$U$)a Reads from the descriptor file until we get to one of the given keywords or reach the end of the file. :param str,list keywords: keyword(s) we want to read until :param file descriptor_file: file with the descriptor content :param bool inclusive: includes the line with the keyword if True :param bool ignore_first: doesn't check if the first line read has one of the given keywords :param bool skip: skips buffering content, returning None :param int end_position: end if we reach this point in the file :param bool include_ending_keyword: provides the keyword we broke on if **True** :returns: **list** with the lines until we find one of the keywords, this is a two value tuple with the ending keyword if include_ending_keyword is **True** N|r)rrrrrr~compileSPECIFIC_KEYWORD_LINErrrrrrr)keywordsr inclusive ignore_firstskip end_positioninclude_ending_keywordr8ending_keywordr keyword_match last_positionrrs r0_read_until_keywordsrs+&Db'. YYx  {H ))+Jg) nnZ **2SXXh5GGH- #((*M 5  # # %D  $$TYY%8%8%D%DT%JKJ!((*1-n ]+  t   nnT/ 2  $$ NrAcSRURS5SS5n[R"[R R RU55$)z Provides the base64 decoded content of a pgp-style block. :param str content: block to be decoded :returns: decoded block content :raises: **TypeError** if this isn't base64 encoded content rrrr)rr rC b64decoderrrrrds r0rrsH GGGMM$'"- .'   $))--77@ AArAcZU(dg[RUS5nU(aUR5Sn/n[U-nU(d"[ SU<SSR U5<35eUR S5nURU5 XT:XaUSR U54$Meg)a Checks if given contents begins with a pseudo-Open-PGP-style block and, if so, pops it off and provides it back to the caller. :param list remaining_contents: lines to be checked for a public key block :returns: **tuple** of the (block_type, content) or None if it doesn't exist :raises: **ValueError** if the contents starts with a key block but it's malformed (for instance, if it lacks an ending line) Nrz+Unterminated pgp style block (looking for 'z'): r)PGP_BLOCK_STARTrr PGP_BLOCK_ENDrrrr)remaining_contents block_matchr+ block_linesend_liners r0_get_pseudo_pgp_blockrs  %%&8&;<+##%a(JKz)H  S[]a]f]fgr]stuu  # #A &d DIIk233  rAc[RR5(d [S5eSSKJn SSKJn SSKJ n UcCURSSU"5S9nS nX@RRl X@RlUR5nS UR!UR"R$UR&R(S 9R+5-n[-XU5$) a Serializes a signing key if we have one. Otherwise this creates a new signing key we can use to create descriptors. .. versionadded:: 1.6.0 :param cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey private_key: private key :returns: :class:`~stem.descriptor.__init__.SigningKey` that can be used to create descriptors :raises: **ImportError** if the cryptography module is unavailable (Signing requires the cryptography modulerr) serialization)rsaii)rkey_sizebackendcg)NrrH)rrs r0no_op!create_signing_key..no_op_s rAr)r(format)rrrr&rrcryptography.hazmat.primitivesr)cryptography.hazmat.primitives.asymmetricrgenerate_private_key_backend_libEVP_PKEY_CTX_set_signature_mdopenssl_assert public_key public_bytesEncodingPEM PublicFormatPKCS1rrq) private_keyrrrr"r,rts r0create_signing_keyr3;s  ( ( * * @ AA::;**!+K?D;*/'%%'**11%%))  ' ' - -2 EG - K] ;;rAc[RR5(d [S5eSSKJn SSKJn [R"URXR5UR555nUSRS/[RRR!US5-S/-5-$) a+ Appends a router signature to a server or extrainfo descriptor. :param bytes content: descriptor content up through 'router-signature\n' :param cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey private_key: private relay signing key :returns: **bytes** with the signed descriptor content rr)hashes)paddingrs-----BEGIN SIGNATURE-----@s-----END SIGNATURE----- )rrrr&r%r5r&r6rCrDraPKCS1v15rrrr_split_by_length)r8r2r5r6rs r0_append_router_signaturer:ns  ( ( * * @ AA3?{//9I9I9KV[[][\) 5::; randrangerBrHrAr0_random_fingerprintrDs% F$$R2X. . 5 5 77rAcS[R"SS5[R"SS5[R"SS5[R"SS54-$)Nz %i.%i.%i.%irr=rHrAr0_random_ipv4_addressrGsI &..C0&..C2H&..YZ\_J`bhbpbpqrtwbxy yyrAc S[R"SS5[R"SS5[R"SS5[R"SS5[R"SS 5[R"SS 54-$) Nz%i-%02i-%02i %02i:%02i:%02iiir r;r=rHrAr0 _random_daterMs &&..t*DfnnUVXZF[]c]k]klmoq]rtzuCuCDEGIuJLRLZLZ[\^`Lacicqcqrsuwcx*y yyrAcF[RRR[R "[ R"S555nSR[RRRUS55nU(aSU<SU<SU<S3$U$)z> Provides a random string that can be used for crypto blocks. rr7z -----BEGIN z----- z -----END z-----) rrrrrCrDrurandomrr9)r+ random_base64 crypto_blobs r0_random_crypto_blobrSsm ))%%11&2B2B2::c?2ST- $))-->>}bQR+;E{T^ __ rAc[U[5(a)[RRR U5n[ 5n/nURS5nU(GaURS5nU(dM"URS5(aUSSn[RU5nU(dU(dMb[SU-5eUR5upU cSn [U5n U (aU upOSupU(aX;aU RS 5 X;aUR)U <S U <35 O#UR+U /5R)XU 45 U(aGMU(aXE4$U$![a U(dGM.ef=f![ aQ SR#U Vs/sHo[$R&;aUOS PM Os snfsn5n[S U <S U<35ef=f)a Initial breakup of the server descriptor contents to make parsing easier. A descriptor contains a series of 'keyword lines' which are simply a keyword followed by an optional value. Lines can also be followed by a signature block. To get a sub-listing with just certain keywords use extra_keywords. This can be useful if we care about their relative ordering with respect to each other. For instance, we care about the ordering of 'accept' and 'reject' entries because this influences the resulting exit policy, but for everything else in server descriptors the order does not matter. :param str raw_contents: descriptor content provided by the relay :param bool validate: checks the validity of the descriptor's content if True, skips these checks otherwise :param list extra_keywords: entity keywords to put into a separate listing with ordering intact :param list non_ascii_fields: fields containing non-ascii content :returns: **collections.OrderedDict** with the 'keyword => (value, pgp key) entries' mappings. If a extra_keywords was provided then this instead provides a two value tuple, the second being a list of those entries. rrzopt Nz$Line contains invalid characters: %srrascii?r|z' line had non-ascii content: rj)rbytesrrrrrr rr KEYWORD_LINErrrrr UnicodeErrorrstring printabler setdefault) raw_contentsrwextra_keywordsnon_ascii_fieldsr extra_entriesremaining_linesrrrr block_attrr+r,charreplaceds r0_descriptor_componentsrfs6 e$$99&&22<@L M'- &&t,/   q !D   v !"Xd##D)J   =D EE&&(NG }e  (9j %/" N%/" NG3V W  gu56 "%,,e-PQs v  !! N+    V77TYZTYDV-=-=%=T3FTYZ['8TUUVs0$E5;E5 F5F  F G*(!G !G*)NrHrHrHr=)T)Frj)FFFNF)rHrH)YrFrCr collectionsr;rJrr>r~r[r stem.prereqr stem.utilstem.util.enumstem.util.str_toolsstem.util.systemrr&stem.util.ordereddict__all__r KEYWORD_CHARrrrYrrrsetr9rDIGEST_PADDINGr CRYPTO_BLOBrenum UppercaseEnum DigestHashr@DocumentHandlerobjectrrREnum Compression namedtuplerhrqrrrrrrrrrrrrr rrr(r0rr=rIrr}rrrr3r:r@rDrGrMrSrfstem.descriptor.bandwidth_file$stem.descriptor.extrainfo_descriptorstem.descriptor.hidden_servicestem.descriptor.microdescriptorstem.descriptor.networkstatus!stem.descriptor.server_descriptorstem.descriptor.tordnselrHrAr0rsVp  0% &  zz|ZPQ /*<**lJWX" CE? YY^^ ) )  --  ))....  @6@F"iinn!! [$ FDcde <8A BC,ww8j kl < e=o pq <&:J KL  R[++,<>hiR$ '' 6\] 375]l]t]tLPZz   CNLE_P/X "  > B"55D **2=@B$!H0