### Install PSAW

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Installs the PSAW library using pip. This is the primary method for getting started with the library.

```bash
pip install psaw
```

--------------------------------

### Install PSAW

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Installs the Python Pushshift.io API Wrapper using pip.

```bash
pip install psaw
```

--------------------------------

### Collect Results into Pandas DataFrame

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Provides an example of how to collect search results from the psaw generator into a pandas DataFrame for easier analysis. It accesses the underlying dictionary data using the '.d_' attribute.

```python
import pandas as pd

df = pd.Dataframe([thing.d_ for thing in gen])
```

--------------------------------

### Get Most Recent Submission by Bot Account

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Demonstrates using the 'stop_condition' argument to retrieve the most recent submission where the author's name contains 'bot'. The loop breaks after finding the first such submission.

```python
gen = api.search_submissions(stop_condition=lambda x: 'bot' in x.author)

for subm in gen:
    pass

print(subm.author)
```

--------------------------------

### Get Most Recent Submission by Bot Account

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Shows how to use the `stop_condition` argument with `search_submissions` to retrieve the most recent submission matching a specific criterion, such as a submission authored by a bot account.

```python
gen = api.search_submissions(stop_condition=lambda x: 'bot' in x.author)

for subm in gen:
    pass

print(subm.author)
```

--------------------------------

### Get Total Results Metadata

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Retrieves the total number of results found on the database side for a given query. This count represents the total items expected after iterating through all pages. Note that there might be rare edge cases with more than 500 items having the same timestamp, which could affect the completeness of returned results. Refer to issue #47 for more details.

```python
api.metadata_.get('total_results')
```

--------------------------------

### PSAW CLI Help

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Provides instructions on how to access the command-line interface (CLI) documentation for PSAW by running the `psaw --help` command.

```APIDOC
psaw --help
```

--------------------------------

### Initialize PushshiftAPI

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Demonstrates how to initialize the PushshiftAPI object for direct use or with a PRAW Reddit instance.

```python
from psaw import PushshiftAPI

api = PushshiftAPI()
```

```python
import praw
from psaw import PushshiftAPI

r = praw.Reddit(...)
api = PushshiftAPI(r)
```

--------------------------------

### Initialize PushshiftAPI

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Demonstrates how to initialize the PushshiftAPI object for making requests.

```python
from psaw import PushshiftAPI

api = PushshiftAPI()
```

--------------------------------

### Initialize PushshiftAPI with PRAW

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Shows how to initialize PushshiftAPI with an existing PRAW Reddit instance to fetch objects using IDs.

```python
import praw
from psaw import PushshiftAPI

r = praw.Reddit(...)
api = PushshiftAPI(r)
```

--------------------------------

### PSAW CLI Help

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Displays the help information for the PSAW command-line interface. This command provides details on available options and usage patterns for interacting with PSAW via the terminal.

```bash
psaw --help
```

--------------------------------

### PushshiftAPI Methods

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Documentation for the core methods of the PushshiftAPI class, including search_comments, search_submissions, and redditor_subreddit_activity. Details parameters, return types, and usage.

```APIDOC
PushshiftAPI:
  search_comments(q: str = None, author: str = None, subreddit: str = None, aggs: str = None, stop_condition: callable = None, ...)
    Searches for comments matching the given criteria.
    Parameters:
      q: Search query string.
      author: Filter by author username.
      subreddit: Filter by subreddit name.
      aggs: Perform aggregations on the results (e.g., 'subreddit').
      stop_condition: A callable that takes a comment object and returns True to stop iteration.
    Returns: A generator yielding comment objects.

  search_submissions(author: str = None, subreddit: str = None, aggs: str = None, stop_condition: callable = None, ...)
    Searches for submissions matching the given criteria.
    Parameters:
      author: Filter by author username.
      subreddit: Filter by subreddit name.
      aggs: Perform aggregations on the results.
      stop_condition: A callable that takes a submission object and returns True to stop iteration.
    Returns: A generator yielding submission objects.

  redditor_subreddit_activity(redditor: str)
    Profiles a redditor's activity by subreddit.
    Parameters:
      redditor: The username of the redditor to profile.
    Returns: A dictionary containing 'comment' and 'submission' Counter objects, mapping subreddits to activity counts.
```

--------------------------------

### PSAW License Information

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Details the licensing information for the PSAW library, stating that it is provided under the Simplified BSD License and includes copyright information.

```APIDOC
License: Simplified BSD License
Copyright (c), 2018, David Marx
```

--------------------------------

### psaw.PushshiftAPI Module

Source: https://github.com/dmarx/psaw/blob/master/docs/source/psaw.rst

This section details the PushshiftAPI module, which is central to interacting with the Pushshift API for fetching Reddit data. It lists all public members, undocumented members, and inheritance information.

```python
from psaw import PushshiftAPI

api = PushshiftAPI()

# Example: Fetch submissions
submissions = list(api.search_submissions(subreddit='python', limit=10))
for sub in submissions:
    print(sub.title)
```

--------------------------------

### Enable Logging for API Requests

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Shows how to enable logging for the psaw library to inspect API request details, such as the URL. It configures a StreamHandler to output INFO level messages from the 'psaw' logger.

```python
import logging 

handler = logging.StreamHandler()
handler.setLevel(logging.INFO)

logger = logging.getLogger('psaw')
logger.setLevel(logging.INFO)
logger.addHandler(handler)
```

--------------------------------

### Search Submissions by Date and Subreddit

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Fetches the first 10 submissions from the '/r/politics' subreddit in 2017, filtering results to specific fields and using a date range.

```python
import datetime as dt

start_epoch=int(dt.datetime(2017, 1, 1).timestamp())

list(api.search_submissions(after=start_epoch,
                            subreddit='politics',
                            filter=['url','author', 'title', 'subreddit'],
                            limit=10))
```

--------------------------------

### psaw.psaw Module

Source: https://github.com/dmarx/psaw/blob/master/docs/source/psaw.rst

This section covers the core psaw module, likely containing the main classes and functions for the package's operations. It includes details on members, undocumented members, and inheritance.

```python
from psaw import PushshiftAPI

# Instantiating the API client
api = PushshiftAPI()

# Searching for comments
comments = api.search_comments(subreddit='learnpython', limit=5)
for comment in comments:
    print(f"Comment ID: {comment.id}, Score: {comment.score}")
```

--------------------------------

### psaw.utilities Module

Source: https://github.com/dmarx/psaw/blob/master/docs/source/psaw.rst

This section describes the utilities module, which likely contains helper functions and tools to assist with data processing or API interactions. It lists members, undocumented members, and inheritance.

```python
from psaw.utilities import get_datetime_string

# Example usage of a utility function
now = get_datetime_string(seconds=1678886400) # Example timestamp
print(f"Formatted datetime: {now}")
```

--------------------------------

### Search Submissions by URL

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Demonstrates searching for submissions by a specific URL. Note that the Pushshift API may not reliably support URL-based filtering, but the `limit` argument should still function.

```python
url = 'http://www.politico.com/story/2017/02/mike-flynn-russia-ties-investigation-235272'
url_results = list(api.search_submissions(url=url, limit=500))
```

--------------------------------

### Metadata Fetching and Error Handling

Source: https://github.com/dmarx/psaw/blob/master/CHANGES.rst

Adds functionality to fetch metadata and includes options to warn or throw exceptions when PushShift shards are detected as down. This improves resilience and provides better feedback on API status.

```python
from psaw import PushshiftAPI

# Initialize with warn_for_shards_down=True to get warnings
api_warn = PushshiftAPI(warn_for_shards_down=True)

# Initialize with throw_for_shards_down=True to raise exceptions
try:
    api_throw = PushshiftAPI(throw_for_shards_down=True)
    # Attempt an operation that might trigger shard down detection
    list(api_throw.search_submissions(subreddit='technology', limit=1))
except Exception as e:
    print(f"Caught exception due to shards being down: {e}")

# Fetching metadata (example)
metadata = api_warn.get_metadata()
print("Pushshift Metadata:", metadata)
```

--------------------------------

### PRAW Integration for Submission Search

Source: https://github.com/dmarx/psaw/blob/master/CHANGES.rst

Enhances the `PushshiftAPI` to accept a `praw.Reddit` instance. When provided, it fetches IDs from Pushshift and passes them to PRAW for more detailed submission analysis.

```python
import praw
from psaw import PushshiftAPI

r = praw.Reddit(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', user_agent='YOUR_USER_AGENT')
api = PushshiftAPI(praw=r)

# Example: Search submissions and use PRAW for details
submissions = list(api.search_submissions(subreddit='python', limit=10))
for sub in submissions:
    print(f"Title: {sub.title}, Score: {sub.score}")
```

--------------------------------

### Search Submissions by Date and Subreddit

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Fetches up to 10 submissions from the '/r/politics' subreddit made in 2017. It filters the results to include only the URL, author, title, and subreddit fields. The `created_utc` field is automatically added for pagination.

```python
import datetime as dt

start_epoch=int(dt.datetime(2017, 1, 1).timestamp())

list(api.search_submissions(after=start_epoch,
                            subreddit='politics',
                            filter=['url','author', 'title', 'subreddit'],
                            limit=10))
```

--------------------------------

### psaw.writers Module

Source: https://github.com/dmarx/psaw/blob/master/docs/source/psaw.rst

This section details the writers module, which is expected to handle the output and storage of retrieved Reddit data. It includes information on members, undocumented members, and inheritance.

```python
from psaw.writers import CSVWriter

# Example of using a writer
writer = CSVWriter('output.csv')

# Assuming 'data' is a list of dictionaries or objects
# writer.write(data)
print("CSVWriter initialized.")
```

--------------------------------

### PSAW Special Attributes and Metadata

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Explains special attributes available on PSAW objects, including `thing.d_` for accessing all data attributes as a dictionary and `api.metadata_` for retrieving request metadata like shard status and total results.

```python
gen = api.search_submissions(subreddit='pushshift')
thing = next(gen)

# Access all data attributes as a dictionary
print(thing.d_)

# Access metadata from the last request
print(api.metadata_.get('shards'))
print(api.metadata_.get('total_results'))
```

--------------------------------

### Fetch 100 Most Recent Submissions

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Retrieves the 100 most recent submissions from Pushshift.io using the `search_submissions` method. The results are returned as a generator and then converted to a list.

```python
# The `search_comments` and `search_submissions` methods return generator objects
gen = api.search_submissions(limit=100)
results = list(gen)
```

--------------------------------

### Summarize Search Results with Aggregations

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Explains how to use the `aggs` parameter to summarize search results. The first item yielded by the generator will contain the aggregation results, typically a count of documents per category.

```python
api = PushshiftAPI()
gen = api.search_comments(author='nasa', aggs='subreddit')
next(gen)
#  {'subreddit': [
#    {'doc_count': 300, 'key': 'IAmA'},
#    {'doc_count': 6, 'key': 'space'},
#    {'doc_count': 1, 'key': 'ExposurePorn'},
#    {'doc_count': 1, 'key': 'Mars'},
#    {'doc_count': 1, 'key': 'OldSchoolCool'},
#    {'doc_count': 1, 'key': 'news'},
#    {'doc_count': 1, 'key': 'pics'},
#    {'doc_count': 1, 'key': 'reddit.com'}]}
len(list(gen)) # 312
```

--------------------------------

### Search Submissions by URL

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Attempts to search for Reddit submissions by a specific URL. Note that URL searching might not be reliably supported by the Pushshift API.

```python
url = 'http://www.politico.com/story/2017/02/mike-flynn-russia-ties-investigation-235272'
url_results = list(api.search_submissions(url=url, limit=500))
```

--------------------------------

### Search Reddit Comments by Text

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Demonstrates how to search for Reddit comments containing specific text within a subreddit. It shows how to handle pagination and collect results, with options for full historical searches or limited results. The `max_results_per_request` parameter controls batch size.

```python
gen = api.search_comments(q='OP', subreddit='askreddit')

max_response_cache = 1000
cache = []

for c in gen:
    cache.append(c)

    # Omit this test to actually return all results. Wouldn't recommend it though: could take a while, but you do you.
    if len(cache) >= max_response_cache:
        break

# If you really want to: pick up where we left off to get the rest of the results.
if False:
    for c in gen:
        cache.append(c)
```

--------------------------------

### Profile Redditor Activity by Subreddit

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Introduces the `redditor_subreddit_activity` convenience method for profiling a user's activity across subreddits. It returns `Counter` objects for both commenting and submission activity, simplifying the aggregation process.

```python
api = PushshiftAPI()
result = api.redditor_subreddit_activity('nasa')
result
#{'comment':
#   Counter({
#      'ExposurePorn': 1,
#      'IAmA': 300,
#      'Mars': 1,
#      'OldSchoolCool': 1,
#      'news': 1,
#      'pics': 1,
#      'reddit.com': 1,
#      'space': 6}),
#'submission':
#   Counter({
#      'IAmA': 3,
#      'ISS': 1,
#      'Mars': 1,
#      'space': 3,
#      'u_nasa': 86})}
```

--------------------------------

### Profile Redditor Subreddit Activity

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Shows how to use the 'redditor_subreddit_activity' convenience method to profile a user's activity across subreddits. It returns Counter objects for commenting and submission activity.

```python
api = PushshiftAPI()
result = api.redditor_subreddit_activity('nasa')
result
#{'comment':
#   Counter({
#      'ExposurePorn': 1,
#      'IAmA': 300,
#      'Mars': 1,
#      'OldSchoolCool': 1,
#      'news': 1,
#      'pics': 1,
#      'reddit.com': 1,
#      'space': 6}),
# 'submission':
#   Counter({
#      'IAmA': 3,
#      'ISS': 1,
#      'Mars': 1,
#      'space': 3,
#      'u_nasa': 86})}
```

--------------------------------

### Aggregations Support in Search Methods

Source: https://github.com/dmarx/psaw/blob/master/CHANGES.rst

Implements support for the `aggs` parameter in search methods. When provided, aggregation results are returned as the first item in the result set, followed by regular search results. Note that PushShift currently limits aggregation results to 100 per query.

```python
from psaw import PushshiftAPI

api = PushshiftAPI()

# Example: Search submissions with aggregations on author
results = list(api.search_submissions(subreddit='learnpython', aggs='author', limit=5))

if results:
    aggregations = results[0]
    print("Aggregations:", aggregations)
    
    # Subsequent results are regular submissions
    for submission in results[1:]:
        print(f"Submission ID: {submission.id}, Author: {submission.author}")
```

--------------------------------

### Collect Results into Pandas DataFrame

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Demonstrates how to collect search results from a PSAW generator into a pandas DataFrame for easier data analysis. It accesses the underlying data dictionary using the `.d_` attribute.

```python
import pandas as pd

df = pd.DataFrame([thing.d_ for thing in gen])
```

--------------------------------

### Add redditor_subreddit_activity convenience method

Source: https://github.com/dmarx/psaw/blob/master/CHANGES.rst

Introduces a new convenience method `redditor_subreddit_activity` for easier access to subreddit activity data. This method aims to simplify common user activity tracking tasks.

```python
def redditor_subreddit_activity(redditor, subreddit):
    # Implementation details for fetching subreddit activity
    pass
```

--------------------------------

### Special Convenience Attributes

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Explains special attributes available on psaw objects. 'thing.d_' provides access to all data attributes as a dictionary, useful for pandas integration. 'api.metadata_' stores metadata from the last request, including shard status.

```python
gen = api.search_submissions(subreddit='pushshift')
thing = next(gen)

# Special attributes:
# * thing.d_ a dict containing all of the data attributes attached to the thing (which otherwise would be accessed via dot notation). One specific convenience this enables is simplifying pushing results into a pandas dataframe (above).
# * api.metadata_ The metadata data provided by pushshift (if any) from the most recent successful request. The most useful metadata attributes, IMHO, are:
#   * api.metadata_.get('shards') - For checking if any shards are down, which can impact the result cardinality.
```

--------------------------------

### Search Comments by Text

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Demonstrates how to search for comments containing specific text ('OP') within a subreddit ('askreddit'). It shows how to handle pagination and potentially retrieve all results by omitting the limit parameter. Requests are batched by 'max_results_per_request'.

```python
gen = api.search_comments(q='OP', subreddit='askreddit')

max_response_cache = 1000
cache = []

for c in gen:
    cache.append(c)

    # Omit this test to actually return all results. Wouldn't recommend it though: could take a while, but you do you.
    if len(cache) >= max_response_cache:
        break

# If you really want to: pick up where we left off to get the rest of the results.
if False:
    for c in gen:
        cache.append(c)
```

--------------------------------

### Fetch 100 Most Recent Submissions

Source: https://github.com/dmarx/psaw/blob/master/README.rst

Retrieves the 100 most recent Reddit submissions using the PushshiftAPI. The search_submissions method returns a generator.

```python
# The `search_comments` and `search_submissions` methods return generator objects
gen = api.search_submissions(limit=100)
results = list(gen)
```

--------------------------------

### Summarize Search Results with Aggregations

Source: https://github.com/dmarx/psaw/blob/master/docs/source/index.rst

Illustrates using the 'aggs' parameter to summarize search results. The first item yielded by the generator will contain the aggregation results, such as subreddit counts for a given author.

```python
api = PushshiftAPI()
gen = api.search_comments(author='nasa', aggs='subreddit')
next(gen)
#  {'subreddit': [
#    {'doc_count': 300, 'key': 'IAmA'},
#    {'doc_count': 6, 'key': 'space'},
#    {'doc_count': 1, 'key': 'ExposurePorn'},
#    {'doc_count': 1, 'key': 'Mars'},
#    {'doc_count': 1, 'key': 'OldSchoolCool'},
#    {'doc_count': 1, 'key': 'news'},
#    {'doc_count': 1, 'key': 'pics'},
#    {'doc_count': 1, 'key': 'reddit.com'}]}
len(list(gen)) # 312
```

--------------------------------

### Support for /reddit/submission/comment_ids/ endpoint

Source: https://github.com/dmarx/psaw/blob/master/CHANGES.rst

Adds support for the `/reddit/submission/comment_ids/` endpoint, enabling retrieval of comment IDs associated with Reddit submissions. This is useful for analyzing comment threads.

```python
from psaw import PushshiftAPI

api = PushshiftAPI()
comment_ids = api.get_submission_comment_ids(submission_id='your_submission_id')
print(comment_ids)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.