Metadata-Version: 2.1
Name: pycookiecheat
Version: 0.7.0
Summary: Borrow cookies from your browser's authenticated session for use in Python scripts.
Author-email: Nathan Henrie <nate@n8henrie.com>
License: MIT
Project-URL: homepage, https://github.com/n8henrie/pycookiecheat
Keywords: pycookiecheat,chrome,chromium cookies,cookies,firefox
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: cryptography ==42.*
Requires-Dist: keyring ==25.*
Provides-Extra: dev
Requires-Dist: build ==1.* ; extra == 'dev'
Requires-Dist: twine ==5.* ; extra == 'dev'
Requires-Dist: wheel ==0.43.* ; extra == 'dev'
Provides-Extra: test
Requires-Dist: black ==24.* ; extra == 'test'
Requires-Dist: flake8-docstrings ==1.* ; extra == 'test'
Requires-Dist: flake8-import-order ==0.18.* ; extra == 'test'
Requires-Dist: flake8 ==7.* ; extra == 'test'
Requires-Dist: mypy ==1.* ; extra == 'test'
Requires-Dist: pep8-naming ==0.13.* ; extra == 'test'
Requires-Dist: playwright ==1.* ; extra == 'test'
Requires-Dist: pycodestyle ==2.* ; extra == 'test'
Requires-Dist: pytest ==8.* ; extra == 'test'
Requires-Dist: tox ==4.* ; extra == 'test'

# pycookiecheat

[![master branch build
status](https://github.com/n8henrie/pycookiecheat/actions/workflows/python-package.yml/badge.svg?branch=master)](https://github.com/n8henrie/pycookiecheat/actions/workflows/python-package.yml)

Borrow cookies from your browser's authenticated session for use in Python
scripts.

-   Free software: MIT
-   Documentation: http://n8h.me/HufI1w

## Installation

**NB:** Use `pip` and `python` instead of `pip3` and `python3` if you're still
on Python 2 and using pycookiecheat < v0.4.0. pycookiecheat >= v0.4.0 requires
Python 3 and in general will aim to support python versions that are stable and
not yet end-of-life: <https://devguide.python.org/versions>.

- `python3 -m pip install pycookiecheat`

### Installation notes regarding alternative keyrings on Linux

See [#12](https://github.com/n8henrie/pycookiecheat/issues/12). Chrome is now
using a few different keyrings to store your `Chrome Safe Storage` password,
instead of a hard-coded password. Pycookiecheat doesn't work with most of these
so far, and to be honest my enthusiasm for adding support for ones I don't use
is limited. However, users have contributed code that seems to work with some
of the recent Ubuntu desktops. To get it working, you may have to `sudo apt-get
install libsecret-1-dev python-gi python3-gi`, and if you're installing into a
virtualenv (highly recommended), you need to use the `--system-site-packages`
flag to get access to the necessary libraries.

Alternatively, some users have suggested running Chrome with the
`--password-store=basic` or `--use-mock-keychain` flags.

### Development Setup

1. `git clone https://github.com/n8henrie/pycookiecheat.git`
1. `cd pycookiecheat`
1. `python3 -m venv .venv`
1. `./.venv/bin/python -m pip install -e .[dev]`

## Usage

### As a Command-Line Tool

As of v0.7.0, pycookiecheat includes a command line tool for ease of use. By
default it prints the cookies to stdout as JSON but can also output a file in
Netscape Cookie File Format.

After installation, the CLI tool can be run as a python module `python -m` or
with a standalone console script:

```console
$ pycookiecheat --help
usage: pycookiecheat [-h] -u URL [-b BROWSER] [-o OUTPUT_FILE]

Copy cookies from Chrome or Firefox and output as json

options:
  -h, --help            show this help message and exit
  -u URL, --url URL     requires scheme (e.g. `https://`)
  -b BROWSER, --browser BROWSER
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        Output to this file in netscape cookie file format
```

### As a Python Library

```python
from pycookiecheat import BrowserType, chrome_cookies
import requests

url = 'https://n8henrie.com'

# Uses Chrome's default cookies filepath by default
cookies = chrome_cookies(url)
r = requests.get(url, cookies=cookies)

# Using an alternate browser
cookies = chrome_cookies(url, browser=BrowserType.CHROMIUM)
```

Use the `cookie_file` keyword-argument to specify a different filepath for the
cookies-file: `chrome_cookies(url, cookie_file='/abspath/to/cookies')`

You may be able to retrieve cookies for alternative Chromium-based browsers by
manually specifying something like
`"/home/username/.config/BrowserName/Default/Cookies"` as your `cookie_file`.

## Features

- Returns decrypted cookies from Google Chrome, Brave, or Slack, on MacOS or
  Linux.
- Optionally outputs cookies to file (thanks to Muntashir Al-Islam!)

## FAQ / Troubleshooting

### How about Windows?

I don't use Windows or have a PC, so I won't be adding support myself. Feel
free to make a PR :)

### I get an installation error with the `cryptography` module on OS X
(pycookiecheat <v0.4.0)

If you're getting [this
error](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221918807)
and using Homebrew, then you need to follow the instructions for [Building
cryptography on OS
X](https://cryptography.io/en/latest/installation/?highlight=cflags#building-cryptography-on-os-x)
and `export LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix
openssl)/include"` and try again.

### I get an installation error with the `cryptography` module on Linux

Please check the official cryptography docs. On some systems (e.g. Ubuntu), you
may need to do something like `sudo apt-get install build-essential libssl-dev
libffi-dev python-dev` prior to installing with `pip`.

### How can I use pycookiecheat on KDE-based Linux distros?

On KDE, Chrome defaults to using KDE's own keyring, KWallet. For pycookiecheat to support KWallet the [`dbus-python`](https://pypi.org/project/dbus-python/) package must be installed.

### How do I install the dev branch with pip?

- `python -m pip install git+https://github.com/n8henrie/pycookiecheat@dev`

## Buy Me a Coffee

[☕️](https://n8henrie.com/donate)

# [Changelog](https://keepachangelog.com)

## v0.7.0 :: 20240105

- Now requires python >= 3.8
    - 3.7 is now EoL: https://devguide.python.org/versions/
    - pycookiecheat seems to build and run on 3.7, but several test
      dependencies require versions that are either incompatible with 3.12 or
      3.7
- Add `BrowserType` enum
    - Instead of passing a string (e.g. "chrome"), please import and use a
      `BrowserType` (e.g. `BrowserType.CHROME`)
    - Add deprecation warning for passing strings
- Added a nix flake to facilitate testing multiple python versions
- Add basic logging
- Add CLI tool
- Add `as_cookies` parameter to allow returning `list[Cookie]` instead of
  `dict` (without breaking backward compatibility)
- Loosen dependency constrains, which should make usage as a library easier

## v0.6.0 :: 20230324

- Add firefox support, thanks to @grandchild
    - Also would like to welcome @grandchild as a new member of the
      pycookiecheat team!

## v0.5.0 :: 20230324

- Add support for Brave thanks to @chrisgavin!
- Add support for Slack thanks to @hraftery!
- Migrate config to pyproject.toml alone
- Minor cleanup to codebase and tests

## v0.4.7 :: 20210826

- No noteworthy API changes, hence the bugfix version bump, but some major
  infrastructure and testing updates:
    - Now uses GitHub Actions instead of Travis
    - Now uses Playwright for testing, to actually open a Chromium instance and
    use a real `Cookies` database
    - PEP517
    - black
- Now requires python >= 3.7
    - This is largely due to requiremets of Playwright:
      https://pypi.org/project/playwright/, which is only a *test* dependency
    - Because I can't *test* with <=3.6, I'm not listing it as compatible,
      though it *probably* will still work
- Migrate to pyproject.toml

## v0.4.6 :: 2019111

- Try to open Chrome database in read-only mode to avoid db locked errors (#29)

## v0.4.5 :: 20191007

- db6ac6d Go back to using cryptography due to
  https://www.cvedetails.com/cve/CVE-2013-7459/
- c70ad51 Allow users to override password (thanks @alairock)

## v0.4.4 :: 20180706

- Optionally outputs cookies to a file compatible with cURL (thanks to
  Muntashir Al-Islam!)

## v0.4.3 :: 20170627

- Consistently use Chrome as default across platforms, allow user to specify
  Chromium as desired (thanks @jtbraun)

## v0.4.0 :: 20170504

- Remove compatibility for Python <3.5
- Add type hints
- Refactor for smaller functions
- Expand docstrings
- Revert from `cryptography` back to `PyCrypto` and `hashlib` for easier
  installation.

## v0.3.4 :: 20170414

- Add support for new Ubuntu keyring / libsecret
  - See <https://github.com/n8henrie/pycookiecheat/issues/12> for details
  - Many thanks to @stat1c1c3au and @trideceth12 for contributions

## 0.3.0

- Use [`cryptography`](https://cryptography.io/en/latest/) instead of
  `pycrypto` (thanks to [Taik](https://github.com/Taik)!)
  - Seems to be [significantly
    faster](https://github.com/n8henrie/pycookiecheat/pull/11#issuecomment-221950400)
  - Works with PyPy >= 2.6.0 (no support for PyPy3 yet)

## 0.2.0

- Fix domain and subdomain matching
- Make SQL query more secure by avoiding string formatting
- Many thanks to [Brandon Rhodes](https://github.com/brandon-rhodes) for 24c4234 !

## 0.1.10

- Read version to separate file so it can be imported in setup.py
- Bugfix for python2 on linux

## 0.1.9

- Bugfix for python2 on linux

## 0.1.8

- Python2 support (thanks [dani14-96](https://github.com/dani14-96))

## 0.1.7

- Configurable cookies file (thanks [ankostis](https://github.com/ankostis))

## 0.1.6

- OSError instead of Exception for wrong OS.
- Moved testing requirements to tox and travis-ci files.

## 0.1.5

- Updated to work better with PyPI's lack of markdown support
- Working on tox and travis-ci integration
- Added a few basic tests that should pass if one has Chrome installed and has visited my site (n8henrie.com)
- Added sys.exit(0) if cookie_file not found so tests pass on travis-ci.

## 0.1.0 (2015-02-25)

- First release on PyPI.

## Prior changelog from Gist

- 20150221 v2.0.1: Now should find cookies for base domain and all subs.
- 20140518 v2.0: Now works with Chrome's new encrypted cookies.
