# letterboxdpy
[](https://badge.fury.io/py/letterboxdpy)
[](https://pepy.tech/project/letterboxdpy)
## Installation
### From PyPI
You can easily install the stable version of `letterboxdpy` from PyPI using pip:
```bash
pip install letterboxdpy
```
### From GitHub Repository
Alternatively, if you wish to access the latest (potentially unstable) version directly from the GitHub repository, you can execute the following command:
```bash
pip install git+https://github.com/nmcassa/letterboxdpy.git
```
> [!WARNING]
> Please be aware that installing directly from the GitHub repository might give you access to the most recent features and bug fixes, but it could also include changes that haven't been thoroughly tested and may not be stable for production use.
<h1 id="User">User Object</h1>
[Explore the file](letterboxdpy/user.py) | [Functions Documentation](/docs/user/funcs/)
```python
from letterboxdpy.user import User
user_instance = User("nmcassa")
print(user_instance)
```
<details>
<summary>Click to expand <code>User</code> object response</summary>
```json
{
"username": "nmcassa",
"url": "https://letterboxd.com/nmcassa",
"id": 1500306,
"is_hq": false,
"display_name": "nmcassa",
"bio": null,
"location": null,
"website": null,
"watchlist_length": 74,
"stats": {
"films": 594,
"this_year": 74,
"lists": 2,
"following": 7,
"followers": 7
},
"favorites": {
"95113": {
"slug": "the-grand-budapest-hotel",
"name": "The Grand Budapest Hotel"
},...
},
"avatar": {
"exists": true,
"upscaled": true,
"url": "https://a.ltrbxd.com/resized/avatar/upload/1/5/0/0/3/0/6/shard/avtr-0-1000-0-1000-crop.jpg"
},
"recent": {
"watchlist": {
"1042841": {
"id": "1042841",
"slug": "the-contestant-2023",
"name": "The Contestant"
},...
},
"diary": {
"months": {
"9": {
"22": [
{
"name": "The Substance",
"slug": "the-substance"
},
{
"name": "Whiplash",
"slug": "1"
}
],
"13": [
{
"name": "Speak No Evil",
"slug": "speak-no-evil-2024"
}
],...
},
"8": {
"30": [
{
"name": "Shaun of the Dead",
"slug": "shaun-of-the-dead"
}
],...
}
}
}
}
}
```
</details>
<h1 id="Movie">Movie Object</h1>
[Explore the file](letterboxdpy/movie.py) | [Functions Documentation](/docs/movie/funcs/)
```python
from letterboxdpy.movie import Movie
movie_instance = Movie("v-for-vendetta")
print(movie_instance)
```
<details>
<summary>Click to expand <code>Movie</code> object response</summary>
```json
{
"scraper": {...},
"url": "https://letterboxd.com/film/v-for-vendetta",
"slug": "v-for-vendetta",
"letterboxd_id": 51400,
"title": "V for Vendetta",
"original_title": null,
"runtime": 132,
"rating": 3.84,
"year": 2005,
"tmdb_link": "https://www.themoviedb.org/movie/752/",
"imdb_link": "http://www.imdb.com/title/tt0434409/maindetails",
"poster": "https://a.ltrbxd.com/resized/film-poster/5/1/4/0/0/51400-v-for-vendetta-0-230-0-345-crop.jpg",
"banner": "https://a.ltrbxd.com/resized/sm/upload/mx/jg/tz/ni/v-for-vendetta-1920-1920-1080-1080-crop-000000.jpg",
"tagline": "People should not be afraid of their governments. Governments should be afraid of their people.",
"description": "In a world in which Great Britain has become a fascist state, a masked vigilante known only as \u201cV\u201d conducts guerrilla warfare against the oppressive British government. When V rescues a young woman from the secret police, he finds in her an ally with whom he can continue his fight to free the people of Britain.",
"trailer": {
"id": "V5VGq23aZ-g",
"link": "https://www.youtube.com/watch?v=V5VGq23aZ-g",
"embed_url": "https://www.youtube.com/embed/V5VGq23aZ-g"
},
"alternative_titles": [
"Vendetta \u00fc\u00e7\u00fcn V",
"O za osvetu",...
],
"details": [
{
"type": "studio",
"name": "Virtual Studios",
"slug": "virtual-studios",
"url": "https://letterboxd.com/studio/virtual-studios/"
},...
],
"genres": [
{
"type": "genre",
"name": "Thriller",
"slug": "thriller",
"url": "https://letterboxd.com/films/genre/thriller/"
},...
],
"cast": [
{
"name": "Natalie Portman",
"role_name": "Evey Hammond",
"slug": "natalie-portman",
"url": "https://letterboxd.com/actor/natalie-portman/"
},...
],
"crew": {
"director": [
{
"name": "James McTeigue",
"slug": "james-mcteigue",
"url": "https://letterboxd.com/director/james-mcteigue/"
}
],
"producer": [
{
"name": "Grant Hill",
"slug": "grant-hill",
"url": "https://letterboxd.com/producer/grant-hill/"
},...
],...
},
"popular_reviews": [
{
"reviewer": "zoey luke",
"rating": " \u2605\u2605\u2605\u2605\u00bd ",
"review": "I love natalie Portman and I hate the government"
},...
]
}
}
```
</details>
<h1 id="Search">Search Object</h1>
[Explore the file](letterboxdpy/search.py) | [Functions Documentation](/docs/search/funcs/)
```python
from letterboxdpy.search import Search
search_instance = Search("V for Vendetta", 'films')
print(search_instance.get_results(max=5))
```
<details>
<summary>Click to expand <code>Search</code> object response</summary>
```json
{
"available": true,
"query": "V%20for%20Vendetta",
"filter": "films",
"end_page": 13,
"count": 5,
"results": [
{
"no": 1,
"page": 1,
"type": "film",
"slug": "v-for-vendetta",
"name": "V for Vendetta",
"year": 2005,
"url": "https://letterboxd.com/film/v-for-vendetta/",
"poster": null,
"directors": [
{
"name": "James McTeigue",
"slug": "james-mcteigue",
"url": "https://letterboxd.com/director/james-mcteigue/"
}
]
},
{
"no": 2,
"page": 1,
"type": "film",
"slug": "lady-vengeance",
"name": "Lady Vengeance",
"year": 2005,
"url": "https://letterboxd.com/film/lady-vengeance/",
"poster": null,
"directors": [
{
"name": "Park Chan-wook",
"slug": "park-chan-wook",
"url": "https://letterboxd.com/director/park-chan-wook/"
}
]
},...
]
}
```
</details>
<h1 id="List">List Object</h1>
[Explore the file](letterboxdpy/list.py)
```python
from letterboxdpy.list import List
list_instance = List("hepburnluv", "classic-movies-for-beginners")
print(list_instance)
```
<details>
<summary>Click to expand <code>List</code> object response</summary>
```json
{
"scraper": {...},
"url": "https://letterboxd.com/hepburnluv/list/classic-movies-for-beginners",
"slug": "classic-movies-for-beginners",
"username": "hepburnluv",
"list_type": "list",
"items_per_page": 60,
"title": "classic movies for beginners.",
"description": "old hollywood classic movies for you who wanna start watching. \u02d6\u207a\u2027\u208a\u02da \u2661 \u02da\u208a\u2027\u207a\u02d6. \u0741\u208a \u22b9 . \u0741(from easiest to hardest to watch) (these are my personal recommendations only) thank you guys for all the comments and likes <3",
"movies": [
[
"The Wizard of Oz",
"the-wizard-of-oz-1939"
],
[
"Roman Holiday",
"roman-holiday"
],...
],
"count": 66
}
```
</details>
<h1 id="Films">Films Object</h1>
[Explore the file](letterboxdpy/films.py) | [Functions Documentation](/docs/films/funcs/)
```python
from letterboxdpy.films import Films
```
<h1 id="Members">Members Object</h1>
[Explore the file](letterboxdpy/members.py) | [Functions Documentation](/docs/members/funcs/)
```python
from letterboxdpy.members import Members
```
<h1 id="Testing">Testing</h1>
You may test the plugin by using the built-in `unittest` package through the CLI:
```zsh
python -m unittest <TEST_FILE_LINK>
```
**Example**
```zsh
python -m unittest tests/test_movie.py
```
## Stargazers over time
[](https://starchart.cc/nmcassa/letterboxdpy)
Raw data
{
"_id": null,
"home_page": null,
"name": "letterboxdpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "FastFingertips <fastfingertips@gmail.com>",
"keywords": "diary, film, letterboxd, movie, rating, review, watchlist, webscraper",
"author": null,
"author_email": "Nicholas Cassarino <nmcassa804@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/50/cf/8a0f2881485aa1e71d688b4df53bf4df418e6ed1e3e11cca1e23e95b97b0/letterboxdpy-5.1.1.tar.gz",
"platform": null,
"description": "# letterboxdpy\n\n[](https://badge.fury.io/py/letterboxdpy)\n[](https://pepy.tech/project/letterboxdpy)\n\n\n## Installation\n\n### From PyPI\n\nYou can easily install the stable version of `letterboxdpy` from PyPI using pip:\n\n```bash\npip install letterboxdpy\n```\n\n### From GitHub Repository\n\nAlternatively, if you wish to access the latest (potentially unstable) version directly from the GitHub repository, you can execute the following command:\n\n```bash\npip install git+https://github.com/nmcassa/letterboxdpy.git\n```\n\n> [!WARNING]\n> Please be aware that installing directly from the GitHub repository might give you access to the most recent features and bug fixes, but it could also include changes that haven't been thoroughly tested and may not be stable for production use.\n\n<h1 id=\"User\">User Object</h1>\n\n[Explore the file](letterboxdpy/user.py) | [Functions Documentation](/docs/user/funcs/)\n\n```python\nfrom letterboxdpy.user import User\nuser_instance = User(\"nmcassa\")\nprint(user_instance)\n```\n\n<details>\n <summary>Click to expand <code>User</code> object response</summary>\n \n```json\n{\n \"username\": \"nmcassa\",\n \"url\": \"https://letterboxd.com/nmcassa\",\n \"id\": 1500306,\n \"is_hq\": false,\n \"display_name\": \"nmcassa\",\n \"bio\": null,\n \"location\": null,\n \"website\": null,\n \"watchlist_length\": 74,\n \"stats\": {\n \"films\": 594,\n \"this_year\": 74,\n \"lists\": 2,\n \"following\": 7,\n \"followers\": 7\n },\n \"favorites\": {\n \"95113\": {\n \"slug\": \"the-grand-budapest-hotel\",\n \"name\": \"The Grand Budapest Hotel\"\n },...\n },\n \"avatar\": {\n \"exists\": true,\n \"upscaled\": true,\n \"url\": \"https://a.ltrbxd.com/resized/avatar/upload/1/5/0/0/3/0/6/shard/avtr-0-1000-0-1000-crop.jpg\"\n },\n \"recent\": {\n \"watchlist\": {\n \"1042841\": {\n \"id\": \"1042841\",\n \"slug\": \"the-contestant-2023\",\n \"name\": \"The Contestant\"\n },...\n },\n \"diary\": {\n \"months\": {\n \"9\": {\n \"22\": [\n {\n \"name\": \"The Substance\",\n \"slug\": \"the-substance\"\n },\n {\n \"name\": \"Whiplash\",\n \"slug\": \"1\"\n }\n ],\n \"13\": [\n {\n \"name\": \"Speak No Evil\",\n \"slug\": \"speak-no-evil-2024\"\n }\n ],...\n },\n \"8\": {\n \"30\": [\n {\n \"name\": \"Shaun of the Dead\",\n \"slug\": \"shaun-of-the-dead\"\n }\n ],...\n }\n }\n }\n }\n}\n```\n</details>\n\n<h1 id=\"Movie\">Movie Object</h1>\n\n[Explore the file](letterboxdpy/movie.py) | [Functions Documentation](/docs/movie/funcs/)\n\n```python\nfrom letterboxdpy.movie import Movie\nmovie_instance = Movie(\"v-for-vendetta\")\nprint(movie_instance)\n```\n\n<details>\n <summary>Click to expand <code>Movie</code> object response</summary>\n\n```json\n{\n \"scraper\": {...},\n \"url\": \"https://letterboxd.com/film/v-for-vendetta\",\n \"slug\": \"v-for-vendetta\",\n \"letterboxd_id\": 51400,\n \"title\": \"V for Vendetta\",\n \"original_title\": null,\n \"runtime\": 132,\n \"rating\": 3.84,\n \"year\": 2005,\n \"tmdb_link\": \"https://www.themoviedb.org/movie/752/\",\n \"imdb_link\": \"http://www.imdb.com/title/tt0434409/maindetails\",\n \"poster\": \"https://a.ltrbxd.com/resized/film-poster/5/1/4/0/0/51400-v-for-vendetta-0-230-0-345-crop.jpg\",\n \"banner\": \"https://a.ltrbxd.com/resized/sm/upload/mx/jg/tz/ni/v-for-vendetta-1920-1920-1080-1080-crop-000000.jpg\",\n \"tagline\": \"People should not be afraid of their governments. Governments should be afraid of their people.\",\n \"description\": \"In a world in which Great Britain has become a fascist state, a masked vigilante known only as \\u201cV\\u201d conducts guerrilla warfare against the oppressive British government. When V rescues a young woman from the secret police, he finds in her an ally with whom he can continue his fight to free the people of Britain.\",\n \"trailer\": {\n \"id\": \"V5VGq23aZ-g\",\n \"link\": \"https://www.youtube.com/watch?v=V5VGq23aZ-g\",\n \"embed_url\": \"https://www.youtube.com/embed/V5VGq23aZ-g\"\n },\n \"alternative_titles\": [\n \"Vendetta \\u00fc\\u00e7\\u00fcn V\",\n \"O za osvetu\",...\n ],\n \"details\": [\n {\n \"type\": \"studio\",\n \"name\": \"Virtual Studios\",\n \"slug\": \"virtual-studios\",\n \"url\": \"https://letterboxd.com/studio/virtual-studios/\"\n },...\n ],\n \"genres\": [\n {\n \"type\": \"genre\",\n \"name\": \"Thriller\",\n \"slug\": \"thriller\",\n \"url\": \"https://letterboxd.com/films/genre/thriller/\"\n },...\n ],\n \"cast\": [\n {\n \"name\": \"Natalie Portman\",\n \"role_name\": \"Evey Hammond\",\n \"slug\": \"natalie-portman\",\n \"url\": \"https://letterboxd.com/actor/natalie-portman/\"\n },...\n ],\n \"crew\": {\n \"director\": [\n {\n \"name\": \"James McTeigue\",\n \"slug\": \"james-mcteigue\",\n \"url\": \"https://letterboxd.com/director/james-mcteigue/\"\n }\n ],\n \"producer\": [\n {\n \"name\": \"Grant Hill\",\n \"slug\": \"grant-hill\",\n \"url\": \"https://letterboxd.com/producer/grant-hill/\"\n },...\n ],...\n },\n \"popular_reviews\": [\n {\n \"reviewer\": \"zoey luke\",\n \"rating\": \" \\u2605\\u2605\\u2605\\u2605\\u00bd \",\n \"review\": \"I love natalie Portman and I hate the government\"\n },...\n ]\n}\n}\n```\n</details>\n\n<h1 id=\"Search\">Search Object</h1>\n\n[Explore the file](letterboxdpy/search.py) | [Functions Documentation](/docs/search/funcs/)\n\n```python\nfrom letterboxdpy.search import Search\nsearch_instance = Search(\"V for Vendetta\", 'films')\nprint(search_instance.get_results(max=5))\n```\n\n<details>\n <summary>Click to expand <code>Search</code> object response</summary>\n\n```json\n{\n \"available\": true,\n \"query\": \"V%20for%20Vendetta\",\n \"filter\": \"films\",\n \"end_page\": 13,\n \"count\": 5,\n \"results\": [\n {\n \"no\": 1,\n \"page\": 1,\n \"type\": \"film\",\n \"slug\": \"v-for-vendetta\",\n \"name\": \"V for Vendetta\",\n \"year\": 2005,\n \"url\": \"https://letterboxd.com/film/v-for-vendetta/\",\n \"poster\": null,\n \"directors\": [\n {\n \"name\": \"James McTeigue\",\n \"slug\": \"james-mcteigue\",\n \"url\": \"https://letterboxd.com/director/james-mcteigue/\"\n }\n ]\n },\n {\n \"no\": 2,\n \"page\": 1,\n \"type\": \"film\",\n \"slug\": \"lady-vengeance\",\n \"name\": \"Lady Vengeance\",\n \"year\": 2005,\n \"url\": \"https://letterboxd.com/film/lady-vengeance/\",\n \"poster\": null,\n \"directors\": [\n {\n \"name\": \"Park Chan-wook\",\n \"slug\": \"park-chan-wook\",\n \"url\": \"https://letterboxd.com/director/park-chan-wook/\"\n }\n ]\n },...\n ]\n}\n```\n</details>\n\n<h1 id=\"List\">List Object</h1>\n\n[Explore the file](letterboxdpy/list.py)\n\n```python\nfrom letterboxdpy.list import List\nlist_instance = List(\"hepburnluv\", \"classic-movies-for-beginners\")\nprint(list_instance)\n```\n\n<details>\n <summary>Click to expand <code>List</code> object response</summary>\n\n```json\n{\n \"scraper\": {...},\n \"url\": \"https://letterboxd.com/hepburnluv/list/classic-movies-for-beginners\",\n \"slug\": \"classic-movies-for-beginners\",\n \"username\": \"hepburnluv\",\n \"list_type\": \"list\",\n \"items_per_page\": 60,\n \"title\": \"classic movies for beginners.\",\n \"description\": \"old hollywood classic movies for you who wanna start watching. \\u02d6\\u207a\\u2027\\u208a\\u02da \\u2661 \\u02da\\u208a\\u2027\\u207a\\u02d6. \\u0741\\u208a \\u22b9 . \\u0741(from easiest to hardest to watch) (these are my personal recommendations only) thank you guys for all the comments and likes <3\",\n \"movies\": [\n [\n \"The Wizard of Oz\",\n \"the-wizard-of-oz-1939\"\n ],\n [\n \"Roman Holiday\",\n \"roman-holiday\"\n ],...\n ],\n \"count\": 66\n}\n```\n</details>\n\n<h1 id=\"Films\">Films Object</h1>\n\n[Explore the file](letterboxdpy/films.py) | [Functions Documentation](/docs/films/funcs/)\n\n```python\nfrom letterboxdpy.films import Films\n```\n\n<h1 id=\"Members\">Members Object</h1>\n\n[Explore the file](letterboxdpy/members.py) | [Functions Documentation](/docs/members/funcs/)\n\n```python\nfrom letterboxdpy.members import Members\n```\n\n<h1 id=\"Testing\">Testing</h1>\n\nYou may test the plugin by using the built-in `unittest` package through the CLI:\n\n```zsh\npython -m unittest <TEST_FILE_LINK>\n```\n\n**Example**\n```zsh\npython -m unittest tests/test_movie.py\n```\n\n## Stargazers over time\n[](https://starchart.cc/nmcassa/letterboxdpy)",
"bugtrack_url": null,
"license": null,
"summary": "A letterboxd webscraper",
"version": "5.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/nmcassa/letterboxdpy/issues",
"Documentation": "https://github.com/nmcassa/letterboxdpy",
"Repository": "https://github.com/nmcassa/letterboxdpy",
"Source Code": "https://github.com/nmcassa/letterboxdpy/archive/refs/heads/main.zip"
},
"split_keywords": [
"diary",
" film",
" letterboxd",
" movie",
" rating",
" review",
" watchlist",
" webscraper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6192c5b945f616969a39bd63dc2e07d8e527ec8a1f529dd2028dd3fbd0f7221e",
"md5": "8c58f873051dfe58b50be53bb1a5979c",
"sha256": "de45463a93c933bbb9a93edd4239d51826c17fe2b5813d7abd7b005d3234d4bf"
},
"downloads": -1,
"filename": "letterboxdpy-5.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c58f873051dfe58b50be53bb1a5979c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 53837,
"upload_time": "2025-07-29T16:53:59",
"upload_time_iso_8601": "2025-07-29T16:53:59.675236Z",
"url": "https://files.pythonhosted.org/packages/61/92/c5b945f616969a39bd63dc2e07d8e527ec8a1f529dd2028dd3fbd0f7221e/letterboxdpy-5.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "50cf8a0f2881485aa1e71d688b4df53bf4df418e6ed1e3e11cca1e23e95b97b0",
"md5": "edbe0082a94ac623746d8ea646690025",
"sha256": "0e268ef18534c022b6da6ec576e80392a26c18464d24390f904568e4fe22213d"
},
"downloads": -1,
"filename": "letterboxdpy-5.1.1.tar.gz",
"has_sig": false,
"md5_digest": "edbe0082a94ac623746d8ea646690025",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 51920,
"upload_time": "2025-07-29T16:54:00",
"upload_time_iso_8601": "2025-07-29T16:54:00.879529Z",
"url": "https://files.pythonhosted.org/packages/50/cf/8a0f2881485aa1e71d688b4df53bf4df418e6ed1e3e11cca1e23e95b97b0/letterboxdpy-5.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 16:54:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nmcassa",
"github_project": "letterboxdpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
"==",
"4.12.3"
]
]
},
{
"name": "lxml",
"specs": [
[
"==",
"5.1.0"
]
]
},
{
"name": "validators",
"specs": []
}
],
"lcname": "letterboxdpy"
}
JSON
