Package: pyspeedinsights
pyspeedinsightsWarning: Archived on 08/11/2023 due to lack of interest. Please consider alternatives such asUnlighthouse.Measure your site speed, performance, accessibility and SEO in bulk from the command line with Python and the PageSpeed Insights API.Support for sitemap parsing and asynchronous requests with aiohttp. Outputs to JSON or a color-coded Excel sheet for further analysis.What is pyspeedinsights?A simple Python cli that parses your sitemap, sends async requests to the PageSpeed Insights API and writes color-coded Lighthouse results to Excel.Why pyspeedinsights?Manually running each page of your website through Google's Lighthouse or PageSpeed Insights can be extremely time consuming, especially if it has a large number of pages.This makes it difficult to analyze its overall performance from a 10,000-foot view without manually testing many similar types of pages.That's what this package attempts to solve. While there are similar tools out there, pyspeedinsights is the first Python implementation built to support analysis in bulk via async requests.Its user-friendly cli gives you the ability to analyze your entire site's speed, SEO, and accessibility results quickly and uncover bottlenecks by reviewing color-coded audit results and metrics for each page in Excel.Format OptionsThe pyspeedinsights cli supports 3 overarching formats:Single page JSON (-f json): Output the raw JSON response from the API to your working directory. If you want to analyze a single page in JSON, use this.Single page Excel (-f excel): Write color-coded Lighthouse audits (any category) and/or PageSpeed CrUX metrics (performance category only) to an Excel sheet. If you want to analyze a single page in Excel, use this.Sitemap / Multi-page Excel (-f sitemap): Specify a sitemap file to parse and output your full site's color-coded Lighthouse audits (any category) and/or PageSpeed CrUX metrics (performance category only) to an Excel sheet. If you want to analyze your entire site in Excel, use this.There are additional customizations available for request parameters and response processing via the cli as well.Please reference thecommandssection for further instructions on how to specify formats and customize other options from the cli.InstallationFrom a virtual environment:pipinstallpyspeedinsightsFrom a system Python3 install on MacOS:python3-mpipinstallpyspeedinsightsFrom a system Python3 install on Windows:py-mpipinstallpyspeedinsightsTo run the package as a module without installing it from PyPI, clone or download it,cdinto thesrcdirectory and run:python-mpyspeedinsightsNote that your PATH, OS or Python version may require that you modify these commands slightly. When in doubt, just install it like you would any other Python package.AuthorizationThe PageSpeed Insights API requires users to generate an API key for anything beyond running basic test requests. Otherwise, you'll hit a rate limit rather quickly.For this reason, a valid API key is currently required to use this package. Please see thePageSpeed Insights API documentationfor detailed instructions on how to generate a key.Keys & QuotasThe key itself is added to the GET request URL as a query parameter.It's recommended to generate the key inGoogle Cloud Console > Credentialsthen restrict it to your host and the PageSpeed Insights API service. If you do go this route, make sure to enable the service inEnabled APIs & Services, as it may not be enabled by default.The API has a daily and per-minute request quota of 25,000 and 240, respectively. To comply with this, the package automatically sleeps requests for 1 second between each call to avoid hitting the per minute quota or overloading the API and getting hit with 500 errors.KeyringThis package uses thekeyringPython library to store API keys securely on your system's default keystore (e.g. MacOS Keychain for MacOS users).Note: If you're unable to use keyring for whatever reason, a fallback input will prompt you for your API key from the command line at the start of each run.The dependency is installed automatically when youpip install pyspeedinsights. If for whatever reason you're getting aImportError: No module named keyringerror, runpip install keyringbefore running anykeyringoperations.Please see thekeyringdocumentationif you require any additional help with the following commands.Saving Your API KeyTo save your API key to your default keystore, run:keyringsetsystempsikeyThe last argument has to bepsikey. This is becausepyspeedinsightslooks for that username to read in your key during requests.systemwill instructkeyringto automatically detect your system's default keystore.You'll then receive a prompt where you can enter your key to save it.Verifying Your API KeyTo verify that your key can be read, run:keyringgetsystempsikeyYour key should be output to the command line.Removing Your API KeyTo remove your API key from your default keystore, run:keyringdelsystempsikeyThen verify that it's no longer accessible withkeyring get system psikey.Sitemap SupportCurrently, only URLs to valid XML sitemaps are supported for reports that utilize sitemap format. Please seesitemaps.orgfor specification details. Gzipped sitemap (e.g.sitemap.xml.gz) support is on the near-term roadmap.Your web server or sitemap plugin must also allow robots to crawl your sitemap. If you see any permission errors that would be the first thing to check. Certain security solutions like CloudFlare also block crawlers so whitelisting the server you're running the package from may also be preferrable.Your sitemap URL should be passed in as the positional argument forurlwhen runningpsifrom the command line.Sitemap IndexSupport for sitemap index detection is also supported. This requires no additional action on your part. Simply pass your sitemap index in as theurlargument via the cli.If a sitemap index is detected, the package will recursively gather the URLs listed in each sitemap in your sitemap index and include them in requests. If a standard sitemap file is passed, only the URLs in that sitemap will be processed.Command Line ArgumentsIf you've installedpyspeedinsightswithpip, the default command to run cli commands ispsi.If you've simply cloned or downloaded the repo, you can run the cli as a module directly withpython -m pyspeedinsights. Make sure tocdinto thesrcdirectory first.For help with the following commands, runpsi --helporpsi -h.Notable Defaultscategory-performancestrategy-desktoplocale-en(US English)QuickstartTo get you started quickly, here are a few example commands.Example of requesting a desktop performance report for all the URLs in your sitemap:psi https://example.com/sitemap.xml -f sitemap -c performance -s desktop -l enEquivalent to:psi https://example.com/sitemap.xml -f sitemapExample of the same report but also specifying a UTM campaign name/source and captcha token:psi https://example.com/sitemap.xml -f sitemap -uc my-campaign-name -us my-campaign-source -t my-captcha-tokenRequest / Sitemap URL:url(required)The URL of the page you want to analyzeora path to a valid XML sitemap/index if sitemap format was selected.This must be a fully qualified url with an optional path. URLs without a scheme default tohttps. URL fragments (#) and query parameters (?) will be removed automatically.Some valid commands:psi https://example.compsi https://www.example.compsi https://example.com/testpsi example.comModified URL:https://example.compsi https://example.com#testModified URL:https://example.comSome invalid commands:psi exampleThrows an errorpsi example/pathThrows an errorSitemap example:psi https://example.com/sitemap.xml -f sitemapParsessitemap.xmland prepares requests for all<loc>elements.Please seesitemapsfor more info.Output Format:-for--format(optional)The format of the Lighthouse results output.json(default): Output the raw JSON response from the API to your working directory (single pages only). You can add a-f jsonargument explicitly or leave it out to simply default to JSON output.excel: Write color-coded Lighthouse audits (any category) and/or PageSpeed CrUX metrics (performance category only) to an Excel sheet (analyze the singleurlonly).sitemap: Specify a sitemap (or index) file to parse and output your full site's color-coded Lighthouse audits (any category) and/or PageSpeed CrUX metrics (performance category only) to an Excel sheet. When using this option, theurlargument above needs to be a direct link to your XML sitemap/index. Please seesitemapsfor more info.Example:psi https://example.com- defaults tojsonpsi https://example.com -f jsonpsi https://example.com -f excelpsi https://example.com -f sitemapMetrics:-mor--metrics(optional)Deprecated in favor of automatically including CrUX metrics if they are available andperformancecategory is selected. The previous metrics were debug metrics and subject to change by Google at any time, which made package maintenance difficult.The new metrics include user-friendly scores instead of raw performance metrics to help give you a quick overview of core metrics like CLS, LCP, etc.Category:-cor--category(optional)The Lighthouse category to run. Defaults toperformance.Other options includeaccessibility,best-practices,pwaandseo.Metrics will only be included with theperformancecategory.Example:psi https://example.com -c accessibilityStrategy:-sor--strategy(optional)The Lighthouse analysis strategy to use. Defaults todesktop.Other options includemobile.Example:psi https://example.com -s mobileLocale:-lor--locale(optional)The locale used to localize formatted results (language). Defaults toen(US).Please see the PSI API docs for afull list of locale options.Example:psi https://example.com -l fr- localize results to FrenchUTM Campaign:-ucor--campaign(optional)The UTM campaign name for analytics. Defaults toNone.This will add a query parameter to the request made by the PageSpeed Insights API (?utm_campaign=audit) so you can differentiate this traffic from real user traffic in Google Analytics.Pass in the name of your campaign,auditis just an example.Example:psi https://example.com -uc auditUTM Source:-usor--source(optional)The UTM campaign source for analytics. Defaults toNone.This will add a query parameter to the request made by the PageSpeed Insights API (?utm_source=psi) so you can differentiate this traffic from real user traffic in Google Analytics.Feel free to customize the name of the source,psiis just an example.Example:psi https://example.com -us psiCaptcha Token:-tor--token(optional)The captcha token passed when filling out a captcha. Defaults toNone.This will add a query parameter to the request made by the PageSpeed Insights API (?utm_source=psi) containing your captcha token. If you have captcha protection enabled on your site, passing this token as an argument to bypass it will ensure that PSI can analyze your site.Example:psi https://example.com -t my-captcha-tokenHelpPlease open an issue on GitHub if you run into any issues or need assistance.ContributingContributors of all skill levels are welcome to help improve this package. Please see theContribution Guidelinesfor details.