Modern Full-featured Twitter API wrapper for Kotlin.
Branch: master
Clone or download
Latest commit a1f28da Feb 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE
gradle/wrapper Upgrade Gradle to 4.10 Jan 16, 2019
src
.gitignore Upgrade Gradle to 4.10 Jan 16, 2019
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
PULL_REQUEST_TEMPLATE.md Add PULL_REQUEST_TEMPLATE.md Jan 9, 2019
README.md
build.gradle.kts Update Kotlin to 1.3.21 and upgrade other deps Feb 7, 2019
gradle.properties Enable Gradle "Parallel Build" Jan 24, 2019
gradlew Remove gradle wrapper Jan 7, 2019
gradlew.bat Initialized Gradle Sep 1, 2017
settings.gradle.kts

README.md

Penicillin: Full-featured Twitter API wrapper for Kotlin

Kotlin 1.3.21 Bintray MIT License GitHub issues GitHub pull requests

  • Supports all the public Twitter API endpoints except Enterprise APIs.
  • Supports the following authenticating methods: OAuth 1.0a, OAuth 2.0
  • Supports some private Twitter API endpoints such as Poll Tweets.
  • Endpoint's parameters are resolved as Kotlin "Typed-safe Named Parameter".
  • Penicillin has model classes. So endpoint's response is easy to use.
  • API execution supports classic function .complete(), suspend function .await() and callback style .queue {}.
  • Cursor APIs such as friends/list have methods named .next, .untilLast(). It makes paging easy.

KDoc is available at docs.nephy.jp. Documentation is WIP :(

Quick example

suspend fun main() {
    // Creates new ApiClient
    val client = PenicillinClient {
        account {
            application("ConsumerKey", "ConsumerSecret")
            token("AccessToken", "AccessToken Secret")
        }
    }

    // Retrieves the user timeline from @realdonaldtrump up to 100.
    client.timeline.user(screenName = "realdonaldtrump", count = 100).await().forEach { status ->
        // prints status text.
        println(status.fullText())
    }

    // Disposes ApiClient
    client.close()
}

More examples of Penicillin can be found at Wiki.

Setup

Latest Penicillin version is Bintray.
Releases are available at Bintray. EAP builds are also available. Every commit is published as EAP build.

You may choose preferred Ktor HttpClient Engine. We recommend using CIO or Apache engine.
Full engine list is available at https://ktor.io/clients/http-client/engines.html.

Gradle Kotlin DSL

We recommend using Gradle Kotlin DSL instead of old build.gradle.

build.gradle.kts

val penicillinVersion = "PUT desired Penicillin version here"
val ktorVersion = "1.1.2"

plugins { 
    kotlin("jvm") version "1.3.21"
}

repositories {
    mavenCentral()
    jcenter()
    maven(url = "https://kotlin.bintray.com/ktor")
    maven(url = "https://kotlin.bintray.com/kotlinx")
    maven(url = "https://kotlin.bintray.com/kotlin-eap")
    maven(url = "https://dl.bintray.com/nephyproject/penicillin")
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation("jp.nephy:penicillin:$penicillinVersion")
    
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    // implementation("io.ktor:ktor-client-apache:$ktorVersion")
    // implementation("io.ktor:ktor-client-jetty:$ktorVersion")
    // implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
}

Gradle

build.gradle

buildscript {
    ext.penicillin_version = "PUT desired Penicillin version here"
    ext.kotlin_version = "1.3.21"
    ext.ktor_version = "1.1.2"

    repositories {
        mavenCentral()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

repositories {
    mavenCentral()
    jcenter()
    maven { url "https://kotlin.bintray.com/ktor" }
    maven { url "https://kotlin.bintray.com/kotlinx" }
    maven { url "https://kotlin.bintray.com/kotlin-eap" }
    maven { url "https://dl.bintray.com/nephyproject/penicillin" } 
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    implementation "jp.nephy:penicillin:$penicillin_version"
    
    implementation "io.ktor:ktor-client-cio:$ktor_version"
    // implementation "io.ktor:ktor-client-apache:$ktor_version"
    // implementation "io.ktor:ktor-client-jetty:$ktor_version"
    // implementation "io.ktor:ktor-client-okhttp:$ktor_version"
}

Multiplatform Support

Currently Penicillin does NOT provide supports for non-JVM environment yet.

In the future, Penicillin is plan to support Kotlin/Multiplatform.

Contributing

License

Penicillin is provided under MIT license. A copy of MIT license of Nephy Project is available here.

Copyright (c) 2017-2019 Nephy Project.