package-twitter 0.1.5

a lightweight Python package designed to simplify programmatic tweeting on Twitter

🐦 Package-Twitter: Programmatic Tweeting with Python

📖 Table of Contents

• 🐦 Package-Twitter: Programmatic Tweeting with Python
  • 📖 Table of Contents
  • 📖 About
  • ✨ Features
  • 🚀 Installation
  • 🔑 Twitter API Setup (Crucial!)
  • 🚀 Quick Start
    • Using the Command-Line Interface (CLI)
    • Using Programmatically in Python
  • 📄 License
  • 👤 Author

---

📖 About

Package-Twitter is a lightweight Python package designed to simplify programmatic tweeting on Twitter (now X). It provides a user-friendly command-line interface (CLI) for quick tweets and a robust Python API for integration into larger applications, bots, or automated workflows. Built on top of tweepy, it offers a straightforward way to interact with the Twitter API v2.

✨ Features

• Simple CLI: Post tweets directly from your terminal.
• Pythonic API: Easily integrate tweeting functionality into your Python applications.
• Secure Credential Handling: Utilizes environment variables to keep your sensitive API keys out of your codebase.
• Robust Error Handling: Provides clear feedback on common Twitter API issues.

🚀 Installation

You can install Package-Twitter directly from PyPI:

pip install package-twitter

NOTE: package-twitter supports python versions 3.11 or later.

🔑 Twitter API Setup (Crucial!)

To use package-twitter, you must obtain Twitter API credentials from the Twitter Developer Portal.

• Apply for a Developer Account: If you don't have one, apply and explain your use case.

• Create a Project and App: Once approved, create a new project and then an app within it.

• Generate API Keys and Tokens: For this app, you will need:

  • Consumer Key (API Key)
  • Consumer Secret (API Secret Key)
  • Access Token
  • Access Token Secret

• Enable "Read and Write" Permissions: Crucially, ensure your app's permissions are set to "Read and Write" in the Developer Portal. Without write permissions, you won't be able to post tweets.

• Set Environment Variables: Create a new python environment or activate a already created environment with python version >=3.11. Then install package-twitter in this environment. Set the API keys as environment variables using the following methods.

  • Using python-dotenv

    • Create a .env file

      Create a new file named .env. This file contains key-value pairs of environment variables. Make sure to provide the following names to the keys. Copy these values and change the placeholders with actual keys.

      TWITTER_CONSUMER_KEY="your_consumer_key_here"
      TWITTER_CONSUMER_SECRET="your_consumer_secret_here"
      TWITTER_ACCESS_TOKEN="your_access_token_here"
      TWITTER_ACCESS_TOKEN_SECRET="your_access_token_secret_here"
      

    • Install the python-dotenv package

      python-dotenv reads key-value pairs from a .env file and can set them as environment variables.

      pip install python-dotenv
      

    • Load .env values in your Python code

      Once the python-dotenv package is installed and the .env file has been created, use the dotenv module along with os.environ to load them into the environment:

      from dotenv import load_dotenv
      import os
      
      # Load environment variables from .env file
      load_dotenv()
      

  • Using shell

    Add these lines to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, ~/.profile for macOS/Linux, or system environment variables for Windows) for persistence.

    export TWITTER_CONSUMER_KEY="your_consumer_key_here"
    export TWITTER_CONSUMER_SECRET="your_consumer_secret_here"
    export TWITTER_ACCESS_TOKEN="your_access_token_here"
    export TWITTER_ACCESS_TOKEN_SECRET="your_access_token_secret_here"
    

    Remember to replace the placeholder values with your actual keys and tokens.

🚀 Quick Start

Once installed and your environment variables are set, you can start tweeting!

Using the Command-Line Interface (CLI)

---

The package provides a tweet command for quick usage:

tweet "Hello Twitter! This tweet was sent using the Package-Twitter CLI."

If you installed from source using Poetry, make sure you're in the project directory and inside the Poetry shell:

cd /path/to/your/package-twitter
poetry shell
tweet "Another tweet via Poetry shell!"

Using Programmatically in Python

---

You can import TwitterBot or tweet_now into your Python scripts:

# my_awesome_bot.py
from package_twitter import TwitterBot, tweet_now
import sys

def post_my_tweet():
    try:
        # Option 1: Using the TwitterBot class directly
        bot = TwitterBot()
        tweet_text_class = "This is a tweet posted using the TwitterBot class directly in Python. #Automation"
        print(f"Attempting to post (class): '{tweet_text_class}'")
        response_class = bot.post_tweet(tweet_text_class)
        if response_class:
            print(f"Tweet posted! ID: {response_class.get('id')}")

        # Option 2: Using the convenience function
        tweet_text_func = "This is another tweet posted using the package_twitter.tweet_now() function. #PythonDev"
        print(f"Attempting to post (function): '{tweet_text_func}'")
        response_func = tweet_now(tweet_text_func)
        if response_func:
            print(f"Tweet posted! ID: {response_func.get('id')}")

    except ValueError as e:
        print(f"Configuration Error: {e}", file=sys.stderr)
    except Exception as e:
        print(f"An unexpected error occurred: {e}", file=sys.stderr)

if __name__ == "__main__":
    post_my_tweet()

To run this script:

py my_awesome_bot.py

📄 License

This project is licensed under the MIT License - see the LICENCE file for details.

👤 Author

Github Profile: Nivesh03

Email: [e-mail]