Repository: dask/dask

Issue:
Inconsistent documentation in read_csv()
From [the documentation](https://docs.dask.org/en/latest/dataframe-api.html#dask.dataframe.read_csv):

> ```python
> read_csv(urlpath, blocksize=64000000,...)
> ```
>...
>**blocksize** : str, int or None, optional
>Number of bytes by which to cut up larger files. Default value is computed based on available physical memory and the number of cores. If None, use a single block for each file. Can be a number like 64000000 or a string like “64MB”

It's unclear whether the default is `64000000` (provided function signature) or unset (doc string).

Playing with a big CSV I have results in the below:
```python
> dd.read_csv("my_file.csv", blocksize="64MB").npartitions
1114
> dd.read_csv("my_file.csv", blocksize="640MB").npartitions
112
> dd.read_csv("my_file.csv", blocksize=None).npartitions
1
> dd.read_csv("my_file.csv").npartitions
1114
```


I've had a look at the source code for calculating blocksize, and I'd expect to see a block size more like 1GB for the machine I'm using right now. I can't actually find where it's being set as `64000000`, as it looks like `read_csv()` is defined via `read_csv = make_reader(pd.read_csv, "read_csv", "CSV")`.


Discussion:
Hi @KrishanBhasin thanks for raising this issue. I agree that the text is confusing. I think that it is technically correct though. The docs say: "Default value is computed based on available physical memory and the number of cores." This step actually happens before the function is defined in the `make_reader` function that you found. Specifically, if you look at that function you'll see that the default blocksize is being set to `AUTO_BLOCKSIZE`: https://github.com/dask/dask/blob/3573b2ddca81aeb41a7def6dd4194020f853ab18/dask/dataframe/io/csv.py#L555

Which in turn is set according to the resources on your machine:

https://github.com/dask/dask/blob/3573b2ddca81aeb41a7def6dd4194020f853ab18/dask/dataframe/io/csv.py#L302-L316

Can you think of a way to make that clearer in the documentation? 
🤦 I found that bit of code and couldn't work out why I was always getting 64MB instead of my 1.5GB.... I somehow understood `min` to actually be `max`
I think the best fix would be:
> Default value is computed based on available physical memory and the number of cores, up to a maximum of 64MB

?
I think the signature in the docs is auto generated, so the machine that its generated on must have an `AUTO_BLOCKSIZE` that computes to`64000000` (?) - I'm not sure how to resolve the inconsistency between that fixed number, and the docs that state it is calculated based on cores/RAM.

Out of interest, why is 64MB the cap?
I experimented with some sphinx options to see if there is a noninvasive way to change the blocksize default in the docs, but it seems like that is very straightforward, and I wouldn't want to hardcode part of the docstring in the docs dir. Given that, I think the best path is to update the description as you suggested with another line that says something like: "NOTE: The default value shown above in the function definition is autogenerated and might be different on your machine."

Resolving patch:
diff --git a/dask/dataframe/io/csv.py b/dask/dataframe/io/csv.py
--- a/dask/dataframe/io/csv.py
+++ b/dask/dataframe/io/csv.py
@@ -319,7 +319,7 @@ def auto_blocksize(total_memory, cpu_count):
 def read_pandas(
     reader,
     urlpath,
-    blocksize=AUTO_BLOCKSIZE,
+    blocksize="default",
     collection=True,
     lineterminator=None,
     compression=None,
@@ -374,6 +374,8 @@ def read_pandas(
     else:
         path_converter = None
 
+    if blocksize == "default":
+        blocksize = AUTO_BLOCKSIZE
     if isinstance(blocksize, str):
         blocksize = parse_bytes(blocksize)
     if blocksize and compression:
@@ -504,10 +506,10 @@ def read_pandas(
     can pass a globstring or a list of paths, with the caveat that they
     must all have the same protocol.
 blocksize : str, int or None, optional
-    Number of bytes by which to cut up larger files. Default value is
-    computed based on available physical memory and the number of cores.
-    If ``None``, use a single block for each file.
-    Can be a number like 64000000 or a string like "64MB"
+    Number of bytes by which to cut up larger files. Default value is computed
+    based on available physical memory and the number of cores, up to a maximum
+    of 64MB. Can be a number like ``64000000` or a string like ``"64MB"``. If
+    ``None``, a single block is used for each file.
 collection : boolean, optional
     Return a dask.dataframe if True or list of dask.delayed objects if False
 sample : int, optional
@@ -552,7 +554,7 @@ def read_pandas(
 def make_reader(reader, reader_name, file_type):
     def read(
         urlpath,
-        blocksize=AUTO_BLOCKSIZE,
+        blocksize="default",
         collection=True,
         lineterminator=None,
         compression=None,


Test patch: