bundle2: small doc update on the bundler

The `bundle20` class contains methods to help define the content and methods
to generate the actual stream. We add small doc headers to help distinguish
between the two.

--HG--
extra : rebase_source : cc2ad0d9ca2dac5f78a0b1c9222ccae9598df14b
bundle2: add a ``newpart`` method to ``bundle20``

Creating new parts is the most common operation people do when exposed to a
bundler. We create a dedicated method on the bundler object for it. This will
simplify the code and also avoid having to import the ``mercurial.bundle2``
module in multiple places.

One part creators have been updated for testing purpose.

--HG--
extra : rebase_source : c6cdf89ef988c1cdf4902e20d38e40d46f3348ca
extra : source : 53a312678ce372b35fa833d260dee051d3f1c61c
bundle2: have ``newpart`` automatically add the part to the bundle

The created part is automatically added to the bundle as this is most certainly
the intent of the user code.

--HG--
extra : rebase_source : 6f86e1ded79f0cb0ffb337e6d4107e6d7c7e519e
bundle2: update all ``addpart`` callers to ``newpart``

The new method is what we want in all current cases.

--HG--
extra : rebase_source : 1a32db40110e1b07f9cd49ccd15656dd9a7a5a34
bundle2: track life cycle of parts

We introduce a ``_generated`` attribute on parts. Coming changesets will
make it easier to update a part's contents after its creation. We need a way to track
if the part is still open to modification or if it is currently being generated
and should not be touched anymore.

As a bonus, we can now detect and crash if someone manages to write bogus code
to get a part generated twice.

--HG--
extra : rebase_source : f268db4bcd3f0845272b59fe60c8c933c2ffd3b4
bundle2: warn about error during initialization in ``newpart`` docstring

As we are moving toward being able to alter a part after its creation, we need
to make the implication of the part being already part of the bundle2 clear.

--HG--
extra : rebase_source : 3f602b2305fe3f7892445760cf0949b3a472d984
bundle2: introduce a ReadOnlyPartError exception

As we will introduce functions to alter already created parts, we need a proper
exception to raise when code tries to alter a part that cannot be altered anymore.

--HG--
extra : rebase_source : 2c047beb8a0c2bc858d15e0818a99d9bea9d0418
bundle2: the ability to set ``data`` attribute of the part is now official

We make it safe to set the data attribute after part creation. It is an allowed
operation as long as the part has not started to be generated.

--HG--
extra : rebase_source : e5ae6b7b1a61680212eabd31b47c1d5e8b9fd25c
bundle2: introduce a ``addparam`` method on part

We make it easier to add new parameters after the part creation. As for the
``data`` attribute we make sure the part generation has not begun yet.

--HG--
extra : rebase_source : ae34328fd1b524226fdfa98e37ed4dd208090846
bundle2: update part creators to ``addparam`` when relevant

In some cases, the use of ``addparam`` makes code much clearer.

--HG--
extra : rebase_source : 432dcf58919802e6249f607e1238c8e1074084ec
bundle2: forbid duplicate parameter keys

No rules were specified about parameter key uniqueness. We document that keys
should be unique and document it. This opens the way to a more friendly (read
dictionary like) way to access value of parameters in the code.

--HG--
extra : rebase_source : f5b08dcb465aace2c71120e261c9e780558e84b1
bundle2: introduce an ``_initparams`` method

The handling of parameters will become much more sophisticated in the coming
changesets. So we extract the logic in a function to not pollute the generic
logic.

--HG--
extra : rebase_source : 5980ddac29fe77fa16c9598a6f8ab9c546b51b66
bundle2: make sure unbundled part param are read-only

My old uncle Robert once trusted an API user. We never saw him again.

--HG--
extra : rebase_source : 40e6b34e97f3176058114746e0bbbc77b82ec14e
bundle2: introduce a ``params`` dictionary on unbundled parts

This exposes all parameters the part received into a ``part.params`` dictionary.
This should be much easier to use.

This dictionary itself does not expose the mandatory or advisory aspect of
parameters, but no current users of bundle2 actually enforce any of this logic.
Coming changesets will improve this aspect.

--HG--
extra : rebase_source : 4c8851e731df6bfe3ac239c422b9948110afa1ea
bundle2: use the new ``part.params`` dictionary

We use the new ``part.params`` dictionary to access the value of parameters instead of
creating one from the part's attributes.

--HG--
extra : rebase_source : 18bb609e2abf33e6e496982532ff218e5bc9be47
bundle2: expose mandatory params in a mandatorykeys attribute

We expose all keys that MUST be processed in ``part.mandatorykeys``. This makes
it much easier to access the information. Enforcement of the mandatory
parameters is coming in later changesets.

--HG--
extra : rebase_source : 59d05d58b40f4ea8a4c7a4a2aeea51fbce2187c5