add documentation

README.md

@@ -9,6 +9,7 @@ This action sets up a Python environment for use in actions by:
 - optionally installing and adding to PATH a version of Python that is already installed in the tools cache.
 - downloading, installing and adding to PATH an available version of Python from GitHub Releases ([actions/python-versions](https://github.com/actions/python-versions/releases)) if a specific version is not available in the tools cache.
 - failing if a specific version of Python is not preinstalled or available for download.
+- optionally caching dependencies for pip and pipenv.
 - registering problem matchers for error output.
 
 # What's new
@@ -18,6 +19,7 @@ This action sets up a Python environment for use in actions by:
 - Automatic setup and download of Python packages if using a self-hosted runner.
 - Support for pre-release versions of Python.
 - Support for installing any version of PyPy on-flight
+- Support for built-in caching of pip and pipenv dependencies
 
 # Usage
 
@@ -205,6 +207,72 @@ pypy-3.7-v7.3.3rc1 # Python 3.7 and preview version of PyPy
 pypy-3.7-nightly # Python 3.7 and nightly PyPy
 ```
 
+# Caching packages dependencies
+
+The action has a built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/cache) under hood for caching dependencies but requires less configuration settings. Supported package managers are `pip` and `pipenv`. The `cache` input is optional, and caching is turned off by default.
+
+The action defaults to search for the dependency file (`requirements.txt` for pip or `Pipfile.lock` for pipenv) in the repository, and uses its hash as a part of the cache key. Use `cache-dependency-path` for cases when multiple dependency files are used, they are located in different subdirectories or different files for hash want to be used.
+
+ - For pip action will cache global cache ditrectory
+ - For pipenv action will cache virtuenv directory
+
+**Caching pip dependencies:**  
+
+```yaml
+steps:
+- uses: actions/checkout@v2
+- uses: actions/setup-python@v2
+  with:
+    python-version: '3.9'
+    cache: 'pip'
+- run: pip install -r requirements.txt
+- run: pip test
+```
+
+**Caching pipenv dependencies:**
+```yaml
+steps:
+- uses: actions/checkout@v2
+- name: Install pipenv
+  run: pipx install pipenv
+- uses: actions/setup-python@v2
+  with:
+    python-version: '3.9'
+    cache: 'pipenv'
+- run: pipenv install
+- run: pipenv test
+```
+
+**Using wildcard patterns to cache dependencies**
+```yaml
+steps:
+- uses: actions/checkout@v2
+- uses: actions/setup-python@v2
+  with:
+    python-version: '3.9'
+    cache: 'pip'
+    cache-dependency-path: '**/requirements-dev.txt'
+- run: pip install -r subdirectory/requirements-dev.txt
+- run: pip test
+```
+
+**Using a list of file paths to cache dependencies**
+```yaml
+steps:
+- uses: actions/checkout@v2
+- name: Install pipenv
+  run: pipx install pipenv
+- uses: actions/setup-python@v2
+  with:
+    python-version: '3.9'
+    cache: 'pipenv'
+    cache-dependency-path: |
+      server/app/Pipfile.lock
+      __test__/app/Pipfile.lock
+- run: pipenv install
+- run: pipenv test
+```
+
 # Using `setup-python` with a self hosted runner
 
 Python distributions are only available for the same [environments](https://github.com/actions/virtual-environments#available-environments) that GitHub Actions hosted environments are available for. If you are using an unsupported version of Ubuntu such as `19.04` or another Linux distribution such as Fedora, `setup-python` will not work. If you have a supported self-hosted runner and you would like to use `setup-python`, there are a few extra things you need to make sure are set up so that new versions of Python can be downloaded and configured on your runner.

dist/setup/index.js

@@ -6633,6 +6633,19 @@ const utils_1 = __webpack_require__(163);
 function isPyPyVersion(versionSpec) {
     return versionSpec.startsWith('pypy-');
 }
+function cacheDepencies(pythonVersion) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const cache = core.getInput('cache');
+        if (cache) {
+            if (utils_1.isGhes()) {
+                throw new Error('Caching is not supported on GHES');
+            }
+            const cacheDependencyPath = core.getInput('cache-dependency-path') || undefined;
+            const cacheDistributor = yield cache_factory_1.getCacheDistributor(cache, pythonVersion, cacheDependencyPath);
+            yield cacheDistributor.restoreCache();
+        }
+    });
+}
 function run() {
     return __awaiter(this, void 0, void 0, function* () {
         try {
@@ -6650,15 +6663,7 @@ function run() {
                     pythonVersion = installed.version;
                     core.info(`Successfully setup ${installed.impl} (${pythonVersion})`);
                 }
-                const cache = core.getInput('cache');
-                if (cache) {
-                    if (utils_1.isGhes()) {
-                        throw new Error('Caching is not supported on GHES');
-                    }
-                    const cacheDependencyPath = core.getInput('cache-dependency-path') || undefined;
-                    const cacheDistributor = yield cache_factory_1.getCacheDistributor(cache, pythonVersion, cacheDependencyPath);
-                    yield cacheDistributor.restoreCache();
-                }
+                yield cacheDepencies(pythonVersion);
             }
             const matchersPath = path.join(__dirname, '../..', '.github');
             core.info(`##[add-matcher]${path.join(matchersPath, 'python.json')}`);

src/setup-python.ts

@@ -10,6 +10,23 @@ function isPyPyVersion(versionSpec: string) {
   return versionSpec.startsWith('pypy-');
 }
 
+async function cacheDepencies(pythonVersion: string) {
+  const cache = core.getInput('cache');
+  if (cache) {
+    if (isGhes()) {
+      throw new Error('Caching is not supported on GHES');
+    }
+    const cacheDependencyPath =
+      core.getInput('cache-dependency-path') || undefined;
+    const cacheDistributor = await getCacheDistributor(
+      cache,
+      pythonVersion,
+      cacheDependencyPath
+    );
+    await cacheDistributor.restoreCache();
+  }
+}
+
 async function run() {
   try {
     const version = core.getInput('python-version');
@@ -28,20 +45,7 @@ async function run() {
         core.info(`Successfully setup ${installed.impl} (${pythonVersion})`);
       }
 
-      const cache = core.getInput('cache');
-      if (cache) {
-        if (isGhes()) {
-          throw new Error('Caching is not supported on GHES');
-        }
-        const cacheDependencyPath =
-          core.getInput('cache-dependency-path') || undefined;
-        const cacheDistributor = await getCacheDistributor(
-          cache,
-          pythonVersion,
-          cacheDependencyPath
-        );
-        await cacheDistributor.restoreCache();
-      }
+      await cacheDepencies(pythonVersion);
     }
     const matchersPath = path.join(__dirname, '../..', '.github');
     core.info(`##[add-matcher]${path.join(matchersPath, 'python.json')}`);