DEPR: deprecate some top-level non-used functions
State: closed

closes #13790

```
pd.pnow()
pd.groupby()
pd.match()
pd.Term
pd.Expr
```
remove info.py


Labels:
name: Deprecate
description: Functionality to remove in pandas

Comments:
@jreback Thanks for the PR!

For me, the main question is, do we actually need those functions? If not, I don't think we have to recommend an alternative import path, but just say they are "deprecated and will be removed in a future version"

- groupby -> referring to the method is of course OK
- pnow -> you *can* also use `Period.now()` (similar to Timestamp.now), so if we do a recommendation, I would refer to that instead of tseries.periods.pnow (that would also mean the actual tseries.periods.pnow can be deprecated, instead of only the top-level one by wrapping it)
- Term / Expr: I never used them, so I can't really judge: do they have a usecase? If so, it is OK to refer to a more nested path for me, but then that should be documented / added to the public API. 
- match: the same. Do we want to have this as a public function? If not, I would recommend the alternative import path.

> - pnow -> you can also use Period.now() (similar to Timestamp.now), so if we do a recommendation, I would refer to that instead of tseries.periods.pnow (that would also mean the actual tseries.periods.pnow can be deprecated, instead of only the top-level one by wrapping it)

didn't realize this, yes I will point that out as instead (and deprecate Period.pnow() as well)

> - Term / Expr: I never used them, so I can't really judge: do they have a usecase? If so, it is OK to refer to a more nested path for me, but then that should be documented / added to the public API.
match: the same. Do we want to have this as a public function? If not, I would recommend the alternative import path.

``Expr``, you never need to directly use this (its used in ``.eval`` under the hood, should not have been exposed at all). ``Term`` *was* needed quite a while back, but string expressions replaced this (years ago).

> - match: the same. Do we want to have this as a public function? If not, I would recommend the alternative import path.

This is barely tested, not documented, and AFAICT never used anywhere. So it might have utility, but certainly not as a top-level function.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15538?src=pr&el=h1) Report
> Merging [#15538](https://codecov.io/gh/pandas-dev/pandas/pull/15538?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/cd677043dcfc4c6b48a6b1ad89da395a35d10e49?src=pr&el=desc) will **decrease** coverage by `-0.02%`.
> The diff coverage is `100%`.


```diff
@@            Coverage Diff             @@
##           master   #15538      +/-   ##
==========================================
- Coverage   91.04%   91.02%   -0.02%     
==========================================
  Files         136      136              
  Lines       49088    49107      +19     
==========================================
+ Hits        44694    44702       +8     
- Misses       4394     4405      +11
```


| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/15538?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/computation/api.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2NvbXB1dGF0aW9uL2FwaS5weQ==) | `100% <100%> (ø)` | :white_check_mark: |
| [pandas/__init__.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL19faW5pdF9fLnB5) | `91.66% <100%> (ø)` | :white_check_mark: |
| [pandas/tseries/period.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvcGVyaW9kLnB5) | `92.8% <100%> (+0.02%)` | :white_check_mark: |
| [pandas/core/api.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXBpLnB5) | `100% <100%> (ø)` | :white_check_mark: |
| [pandas/io/api.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2lvL2FwaS5weQ==) | `100% <100%> (ø)` | :white_check_mark: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :x: |
| [pandas/tools/merge.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL3Rvb2xzL21lcmdlLnB5) | `91.78% <0%> (-0.35%)` | :x: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.82% <0%> (-0.1%)` | :x: |
| [pandas/tseries/index.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvaW5kZXgucHk=) | `95.32% <0%> (-0.1%)` | :x: |
| [pandas/core/common.py](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tbW9uLnB5) | `91.36% <0%> (+0.33%)` | :white_check_mark: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15538?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/15538?src=pr&el=footer). Last update [cd67704...59d2b61](https://codecov.io/gh/pandas-dev/pandas/compare/cd677043dcfc4c6b48a6b1ad89da395a35d10e49...59d2b6182491e5b359475ad4ccba032cf40b5ae0?el=footer&src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
so we have this mini example in 

http://pandas-docs.github.io/pandas-docs-travis/comparison_with_r.html

```
In [1]: s = pd.Series(np.arange(5),dtype=np.float32)

In [2]: s
Out[2]: 
0    0.0
1    1.0
2    2.0
3    3.0
4    4.0
dtype: float32

In [3]: pd.Series(pd.match(s,[2,4],np.nan))
Out[3]: 
0    NaN
1    NaN
2    0.0
3    NaN
4    1.0
dtype: float64
```

which is actually confusing / misleading.
```

In [7]: s.where(s.isin([2,4]))
Out[7]: 
0    NaN
1    NaN
2    2.0
3    NaN
4    4.0
dtype: float32
```

is much more useful (I don't know why you would want that kind of transformation)

though I don't use R much, so not sure what it is trying to show.
Hmm, I would maybe just remove that example (`isin` is already showed just above the `match` example). 
match has its use (if you want exactly what is in the example), question is whether we need to support that.

@jorisvandenbossche yep sounds good. Yeah the function still exists, its just not top-level (like ``.unique``, ``.factorize``, ``.value_counts``); though even the latter 2 don't really need to be exposed directly to the user (``.value_counts`` is a method, ``.factorize`` is just an implementation detail for ``category``).

These made much more sense when directly allowing numpy arrays was useful (but that is less and less useful). But this is another story.

ok will remove that part of the doc.