a *Na$Q@sdZddlZddlZddlZddlmZddlZddlmZGddde Z Gdd d e Z d d Z Gd d d e ZddZddZddZejddZddZddZGddde ZGdddejZGddde ZGd d!d!e ZdS)"z requests_toolbelt.multipart.encoder =================================== This holds all of the implementation details of the MultipartEncoder N)uuid4fieldsc@seZdZdZdS)FileNotSupportedErrorzFile not supported error.N)__name__ __module__ __qualname____doc__r r ~/private/var/folders/js/6pj4vh5d4zd0k6bxv74qrbhr0000gr/T/pip-target-22xwyzbs/lib/python/requests_toolbelt/multipart/encoder.pyrsrc@seZdZdZd%ddZeddZdd Zd d Zd d Z ddZ ddZ ddZ ddZ ddZddZddZddZeddZd d!Zd&d#d$ZdS)'MultipartEncodera The ``MultipartEncoder`` object is a generic interface to the engine that will create a ``multipart/form-data`` body for you. The basic usage is: .. code-block:: python import requests from requests_toolbelt import MultipartEncoder encoder = MultipartEncoder({'field': 'value', 'other_field', 'other_value'}) r = requests.post('https://httpbin.org/post', data=encoder, headers={'Content-Type': encoder.content_type}) If you do not need to take advantage of streaming the post body, you can also do: .. code-block:: python r = requests.post('https://httpbin.org/post', data=encoder.to_string(), headers={'Content-Type': encoder.content_type}) If you want the encoder to use a specific order, you can use an OrderedDict or more simply, a list of tuples: .. code-block:: python encoder = MultipartEncoder([('field', 'value'), ('other_field', 'other_value')]) .. versionchanged:: 0.4.0 You can also provide tuples as part values as you would provide them to requests' ``files`` parameter. .. code-block:: python encoder = MultipartEncoder({ 'field': ('file_name', b'{"a": "b"}', 'application/json', {'X-My-Header': 'my-value'}) ]) .. warning:: This object will end up directly in :mod:`httplib`. Currently, :mod:`httplib` has a hard-coded read size of **8192 bytes**. This means that it will loop until the file has been read and your upload could take a while. This is **not** a bug in requests. A feature is being considered for this object to allow you, the user, to specify what size should be returned on a read. If you have opinions on this, please weigh in on `this issue`_. .. _this issue: https://github.com/requests/toolbelt/issues/75 Nutf-8cCs|p tj|_d|j|_||_dt|j|jtd|jg|_||_ d|_ g|_ t g|_ d|_d|_t|d|_||dS)Nz--{0}z F)encoding)rhexboundary_valueformatboundaryrjoin encode_with_encoded_boundaryrfinishedpartsiter _iter_parts _current_part_len CustomBytesIO_buffer_prepare_parts_write_boundary)selfrrrr r r __init__Ws     zMultipartEncoder.__init__cCs|jp |S)aiLength of the multipart/form-data body. requests will first attempt to get the length of the body by calling ``len(body)`` and then by checking for the ``len`` attribute. On 32-bit systems, the ``__len__`` method cannot return anything larger than an integer (in C) can hold. If the total size of the body is even slightly larger than 4GB users will see an OverflowError. This manifested itself in `bug #80`_. As such, we now calculate the length lazily as a property. .. _bug #80: https://github.com/requests/toolbelt/issues/80 )r_calculate_lengthr"r r r lenszMultipartEncoder.lencCs d|jS)Nz)rrr%r r r __repr__szMultipartEncoder.__repr__cs2t|jtfdd|jDd|_|jS)z This uses the parts to calculate the length of the body. This returns the calculated length so __len__ can be lazy. c3s|]}t|dVqdS)N) total_len).0pZ boundary_lenr r sz5MultipartEncoder._calculate_length..r()r&rsumrrr%r r,r r$s  z"MultipartEncoder._calculate_lengthcCs|t|j}|dkr|SdS)aThis calculates how many bytes need to be added to the buffer. When a consumer read's ``x`` from the buffer, there are two cases to satisfy: 1. Enough data in the buffer to return the requested amount 2. Not enough data This function uses the amount of unread bytes in the buffer and determines how much the Encoder has to load before it can return the requested amount of bytes. :param int read_size: the number of bytes the consumer requests :returns: int -- the number of bytes that must be loaded into the buffer before the read can be satisfied. This will be strictly non-negative r)r)r)r" read_sizeamountr r r _calculate_load_amountsz'MultipartEncoder._calculate_load_amountcCs|j|jp|}|dks(|dkrd}|rZ|sZ||d7}||7}|}|sr||7}d|_q|| |j|7}|dkr||8}qdS)z0Load ``amount`` number of bytes into the buffer.rs TN) rsmart_truncater _next_partbytes_left_to_write_writer!_write_closing_boundaryrwrite_to)r"r0partwrittenr r r _loads    zMultipartEncoder._loadcCs0zt|j}|_Wnty*d}Yn0|SN)nextrr StopIteration)r"r+r r r r4s   zMultipartEncoder._next_partc cs|j}t|jdr t|j}|D]\}}d}d}d}t|ttfrt|dkr\|\}}qt|dkrt|\}}}q|\}}}}n|}tj||||d}|j|d|Vq$dS)Nitemsr)namedatafilenameheaders) content_type) rhasattrlistr? isinstancetupler& RequestFieldmake_multipart) r"_fieldskv file_name file_typeZ file_headersZ file_pointerfieldr r r _iter_fieldss(       zMultipartEncoder._iter_fieldscs.|jfdd|D|_t|j|_dS)zThis uses the fields provided by the user and creates Part objects. It populates the `parts` attribute and uses that to create a generator for iteration. csg|]}t|qSr )Part from_field)r*fencr r rz3MultipartEncoder._prepare_parts..N)rrRrrrr%r rVr r szMultipartEncoder._prepare_partscCs |j|S)zWrite the bytes to the end of the buffer. :param bytes bytes_to_write: byte-string (or bytearray) to append to the buffer :returns: int -- the number of bytes written )rappend)r"Zbytes_to_writer r r r6szMultipartEncoder._writecCs ||jS)z,Write the boundary to the end of the buffer.)r6rr%r r r r!sz MultipartEncoder._write_boundarycCsHt|j*|jdd|jdWdn1s:0YdS)z?Write the bytes necessary to finish a multipart/form-data body.rs-- N)resetrseekwriter%r r r r7s *z(MultipartEncoder._write_closing_boundarycCs|t||jS)z/Write the current part's headers to the buffer.)r6rr)r"rDr r r _write_headers szMultipartEncoder._write_headerscCstd|jS)Nz!multipart/form-data; boundary={0})strrrr%r r r rEs zMultipartEncoder.content_typecCs|S)aReturn the entirety of the data in the encoder. .. note:: This simply reads all of the data it can. If you have started streaming or reading data from the encoder, this method will only return whatever data is left in the encoder. .. note:: This method affects the internal state of the encoder. Calling this method will exhaust the encoder. :returns: the multipart message :rtype: bytes readr%r r r to_stringszMultipartEncoder.to_stringr2cCsJ|jr|j|S|}|dkr4|dur4|t|}|||j|S)zRead data from the streaming encoder. :param int size: (optional), If provided, ``read`` will return exactly that many bytes. If it is not provided, it will return the remaining bytes. :returns: bytes r2N)rrrar1intr;)r"sizeZ bytes_to_loadr r r ra+s  zMultipartEncoder.read)Nr)r2)rrr r r#propertyr&r'r$r1r;r4rRr r6r!r7r^rErbrar r r r r s&= +     r cCs|Sr<r )Zmonitorr r r IDENTITY>srfc@sFeZdZdZdddZedddZedd Zd d Z dd dZ dS)MultipartEncoderMonitora An object used to monitor the progress of a :class:`MultipartEncoder`. The :class:`MultipartEncoder` should only be responsible for preparing and streaming the data. For anyone who wishes to monitor it, they shouldn't be using that instance to manage that as well. Using this class, they can monitor an encoder and register a callback. The callback receives the instance of the monitor. To use this monitor, you construct your :class:`MultipartEncoder` as you normally would. .. code-block:: python from requests_toolbelt import (MultipartEncoder, MultipartEncoderMonitor) import requests def callback(monitor): # Do something with this information pass m = MultipartEncoder(fields={'field0': 'value0'}) monitor = MultipartEncoderMonitor(m, callback) headers = {'Content-Type': monitor.content_type} r = requests.post('https://httpbin.org/post', data=monitor, headers=headers) Alternatively, if your use case is very simple, you can use the following pattern. .. code-block:: python from requests_toolbelt import MultipartEncoderMonitor import requests def callback(monitor): # Do something with this information pass monitor = MultipartEncoderMonitor.from_fields( fields={'field0': 'value0'}, callback ) headers = {'Content-Type': montior.content_type} r = requests.post('https://httpbin.org/post', data=monitor, headers=headers) NcCs$||_|p t|_d|_|jj|_dSNr)encoderrfcallback bytes_readr&)r"rirjr r r r#us z MultipartEncoderMonitor.__init__rcCst|||}|||Sr<)r )clsrrrrjrir r r from_fieldss z#MultipartEncoderMonitor.from_fieldscCs|jjSr<)rirEr%r r r rEsz$MultipartEncoderMonitor.content_typecCs|Sr<r`r%r r r rbsz!MultipartEncoderMonitor.to_stringr2cCs,|j|}|jt|7_|||Sr<)rirarkr&rj)r"rdstringr r r ras  zMultipartEncoderMonitor.read)N)NrN)r2) rrr r r# classmethodrmrerErbrar r r r rgBs1   rgcCs |dust|ts||S|S)a6Encoding ``string`` with ``encoding`` if necessary. :param str string: If string is a bytes object, it will not encode it. Otherwise, this function will encode it with the provided encoding. :param str encoding: The encoding with which to encode string. :returns: encoded bytes object N)rHbytesencode)rnrr r r rs rcCst|dr|St||S)z4Coerce the data to an object with a ``read`` method.ra)rFrrBrr r r readable_datas rscCstt|drt|St|dr"|jSt|drZz |}WntjyLYn0t|jSt|drpt|SdS)N__len__r&filenogetvalue) rFr&ruioUnsupportedOperationosfstatst_sizerv)orur r r r)s      r)ccs*|}|dddV||ddS)aKeep track of the buffer's current position and write to the end. This is a context manager meant to be used when adding data to the buffer. It eliminates the need for every function to be concerned with the position of the cursor in the buffer. rrNtellr\)bufferZoriginal_positionr r r r[s r[cCsLt|tsHt|dr"t||St|dr4t|St|dsHt||S|S)z5Ensure that every object's __len__ behaves uniformly.rvrura)rHrrFrv FileWrapperrrr r r coerce_datas     rcCst|drt|St|S)Nr?)rFrGr?rr r r to_lists  rc@s0eZdZddZeddZddZddZd S) rScCs,||_||_d|_t|jt|j|_dS)NT)rDbodyheaders_unreadr&r))r"rDrr r r r#sz Part.__init__cCs$t||}t|j|}|||S)z8Create a part from a Request Field generated by urllib3.)rrender_headersrrB)rlrQrrDrr r r rTs zPart.from_fieldcCs*d}|jr|t|j7}|t|jdkS)zDetermine if there are bytes left to write. :returns: bool -- ``True`` if there are bytes left to write, otherwise ``False`` r)rr&rDr)r)r"Zto_readr r r r5szPart.bytes_left_to_writecCsnd}|jr |||j7}d|_t|jdkrj|dks>||krj|}|dkrR||}|||j|7}q |S)aWrite the requested amount of bytes to the buffer provided. The number of bytes written may exceed size on the first read since we load the headers ambitiously. :param CustomBytesIO buffer: buffer we want to write bytes to :param int size: number of bytes requested to be written to the buffer :returns: int -- number of bytes actually written rFr2)rrYrDr)rra)r"rrdr:Zamount_to_readr r r r8s z Part.write_toN)rrr r#rorTr5r8r r r r rSs   rScsBeZdZd fdd ZddZeddZd d Zd d ZZ S)rNrcst||}tt||dSr<)rsuperrr#)r"rr __class__r r r#s zCustomBytesIO.__init__cCs,|}|dd|}||d|S)Nrrr})r"Z current_poslengthr r r _get_ends   zCustomBytesIO._get_endcCs|}||Sr<)rr~r"rr r r r&!szCustomBytesIO.lencCs6t|||}Wdn1s(0Y|Sr<)r[r])r"rpr:r r r rY&s (zCustomBytesIO.appendcCsRt|}||}||krN|}|dd||||dddSrh)r)rrar\truncater])r"Z to_be_readZ already_readZ old_bytesr r r r3+s   zCustomBytesIO.smart_truncate)Nr) rrr r#rrer&rYr3 __classcell__r r rr rs  rc@s*eZdZddZeddZd ddZdS) rcCs ||_dSr<)fd)r"Z file_objectr r r r#8szFileWrapper.__init__cCst|j|jSr<)r)rr~r%r r r r&;szFileWrapper.lenr2cCs |j|Sr<)rrarr r r ra?szFileWrapper.readN)r2)rrr r#rer&rar r r r r7s rc@s*eZdZdZd ddZddZddZdS) FileFromURLWrapperaFile from URL wrapper. The :class:`FileFromURLWrapper` object gives you the ability to stream file from provided URL in chunks by :class:`MultipartEncoder`. Provide a stateless solution for streaming file from one server to another. You can use the :class:`FileFromURLWrapper` without a session or with a session as demonstated by the examples below: .. code-block:: python # no session import requests from requests_toolbelt import MultipartEncoder, FileFromURLWrapper url = 'https://httpbin.org/image/png' streaming_encoder = MultipartEncoder( fields={ 'file': FileFromURLWrapper(url) } ) r = requests.post( 'https://httpbin.org/post', data=streaming_encoder, headers={'Content-Type': streaming_encoder.content_type} ) .. code-block:: python # using a session import requests from requests_toolbelt import MultipartEncoder, FileFromURLWrapper session = requests.Session() url = 'https://httpbin.org/image/png' streaming_encoder = MultipartEncoder( fields={ 'file': FileFromURLWrapper(url, session=session) } ) r = session.post( 'https://httpbin.org/post', data=streaming_encoder, headers={'Content-Type': streaming_encoder.content_type} ) NcCs4|p t|_||}t|jd|_|j|_dS)Ncontent-length) requestsSessionsession_request_for_filercrDr&rawraw_data)r"file_urlrZrequested_filer r r r#qs zFileFromURLWrapper.__init__cCs\|jj|dd}|jdd}|durs.  (U  2"