ENH: Adding 'protocol' parameter to 'to_pickle'.
State: closed

This PR aims at adding an optional `protocol` parameter to the function `to_pickle`. 
Closes #14488. If needed, I can update the corresponding test (`pandas/tests/io/test_pickle.py`).

Labels:
name: Enhancement
name: IO Data
description: IO issues that don't fit into a more specific label
name: Compat
description: pandas objects compatability with Numpy or Python functions

Comments:
tests are the first thing you should write.
also add a whatsnew in enhancements for 0.21.0
I am facing an issue when writing the tests.
I Installed a pandas-dev environment as suggested in http://pandas.pydata.org/pandas-docs/stable/contributing.html. When I try to run `pytests` on `pandas/tests/io/test_pickle.py`, I get the following error :

```
 % pytest test_pickle.py                                                                                                                                                                                             ~/pandas/pandas/tests/io
============================================================================================================ test session starts =============================================================================================================
platform linux -- Python 3.6.1, pytest-3.0.7, py-1.4.33, pluggy-0.4.0
rootdir: /cal/homes/jbschiratti/pandas, inifile: setup.cfg
plugins: cov-2.3.1
collected 42 items 

test_pickle.py ..........................................Traceback (most recent call last):
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/bin/pytest", line 6, in <module>
    sys.exit(pytest.main())
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/config.py", line 57, in main
    return config.hook.pytest_cmdline_main(config=config)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 745, in __call__
    return self._hookexec(self, self._nonwrappers + self._wrappers, kwargs)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 339, in _hookexec
    return self._inner_hookexec(hook, methods, kwargs)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 334, in <lambda>
    _MultiCall(methods, kwargs, hook.spec_opts).execute()
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 614, in execute
    res = hook_impl.function(*args)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/main.py", line 127, in pytest_cmdline_main
    return wrap_session(config, _main)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/main.py", line 122, in wrap_session
    exitstatus=session.exitstatus)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 745, in __call__
    return self._hookexec(self, self._nonwrappers + self._wrappers, kwargs)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 339, in _hookexec
    return self._inner_hookexec(hook, methods, kwargs)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 334, in <lambda>
    _MultiCall(methods, kwargs, hook.spec_opts).execute()
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 613, in execute
    return _wrapped_call(hook_impl.function(*args), self.execute)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 250, in _wrapped_call
    wrap_controller.send(call_outcome)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/terminal.py", line 358, in pytest_sessionfinish
    outcome.get_result()
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 279, in get_result
    raise ex[1].with_traceback(ex[2])
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 265, in __init__
    self.result = func()
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/vendored_packages/pluggy.py", line 614, in execute
    res = hook_impl.function(*args)
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/cacheprovider.py", line 152, in pytest_sessionfinish
    prev_failed = config.cache.get("cache/lastfailed", None) is not None
  File "/cal/homes/jbschiratti/anaconda3/envs/pandas_dev/lib/python3.6/site-packages/_pytest/cacheprovider.py", line 57, in get
    return json.load(f)
AttributeError: module 'json' has no attribute 'load'
```
Is it because it indirectly calls the wrong `json` module ?
Try changing to the root of the git repo and running `pandas/tests/io/test_pickle.py`
@TomAugspurger It solved my problem. Thanks! 
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=h1) Report
> Merging [#16252](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/a31c96d34d00dc757908b564dc93991e867d83e2?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/16252/graphs/tree.svg?height=150&width=650&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #16252      +/-   ##
==========================================
- Coverage   90.33%   90.32%   -0.01%     
==========================================
  Files         164      164              
  Lines       50890    50891       +1     
==========================================
- Hits        45972    45969       -3     
- Misses       4918     4922       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.11% <100%> (+0.01%)` | :arrow_up: |
| #single | `40.3% <60%> (-0.1%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `91.72% <100%> (ø)` | :arrow_up: |
| [pandas/io/pickle.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL3BpY2tsZS5weQ==) | `79.54% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.58% <0%> (-0.1%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.23% <0%> (-0.1%)` | :arrow_down: |
| [pandas/core/common.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tbW9uLnB5) | `91.03% <0%> (+0.34%)` | :arrow_up: |
| [pandas/\_version.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL192ZXJzaW9uLnB5) | `44.65% <0%> (+1.9%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=footer). Last update [a31c96d...04bc5c2](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=h1) Report
> Merging [#16252](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/a31c96d34d00dc757908b564dc93991e867d83e2?src=pr&el=desc) will **increase** coverage by `0.04%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/16252/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #16252      +/-   ##
==========================================
+ Coverage   90.33%   90.38%   +0.04%     
==========================================
  Files         164      161       -3     
  Lines       50890    50967      +77     
==========================================
+ Hits        45972    46067      +95     
+ Misses       4918     4900      -18
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.16% <100%> (+0.05%)` | :arrow_up: |
| #single | `40.2% <50%> (-0.21%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/pickle.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL3BpY2tsZS5weQ==) | `80.43% <100%> (+0.88%)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `92.13% <100%> (+0.4%)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/io/msgpack/\_version.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL21zZ3BhY2svX3ZlcnNpb24ucHk=) | `44.86% <0%> (-55.14%)` | :arrow_down: |
| [pandas/core/util/hashing.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvdXRpbC9oYXNoaW5nLnB5) | `92.96% <0%> (-6.08%)` | :arrow_down: |
| [pandas/core/computation/expressions.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tcHV0YXRpb24vZXhwcmVzc2lvbnMucHk=) | `90.47% <0%> (-2.21%)` | :arrow_down: |
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.18% <0%> (-0.31%)` | :arrow_down: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.56% <0%> (-0.17%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `94.71% <0%> (-0.09%)` | :arrow_down: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `95.66% <0%> (ø)` | :arrow_up: |
| ... and [36 more](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=footer). Last update [a31c96d...8eb660d](https://codecov.io/gh/pandas-dev/pandas/pull/16252?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

this needs some tests.
I'm on it. I'll make a new commit, very soon, with the necessary tests. 
@jreback I added some tests for valid and invalid values of the `protocol` parameter. Please, have a look and tell me if more tests are needed or if there is a problem with the code.
@jreback : Do you think that more tests are needed ?
small linting failure.
Oupps! Fixed the linting failure. Should be OK now.
With my previous commit, all tests were successful. After modifying docstrings and the whatsnew file, `test_clipboard` is failing, according to Travis. Is there something wrong with my recent changes ?
I restarted that CI job. sometimes that tests fails :<

minor comment on docs. just ping when pushed.
@jreback : I pushed the changes.
thanks!
keep em coming!